turbine-orm 0.81.0 → 0.90.0

package/dist/client.js

@@ -22,19 +22,29 @@
  * ```
  */
 import pg from '#pg';
-import { openCheckout } from './checkout.js';
-import { absorbCheckedOutErrors, settleLongIdleCheckouts } from './connection-guard.js';
-import { mergeConnectionStringOptions } from './connection-url.js';
+import { openCheckout, typeCheckoutTimeouts } from './checkout.js';
+import { absorbCheckedOutErrors, settleLongIdleCheckouts, watchCheckouts, } from './connection-guard.js';
+import { detectPoolerTarget, fillTargetFromEnvironment, parseConnectionTarget, statementTimeoutSetting, withStartupSetting, } from './connection-url.js';
+import { resolveDiagnostics } from './diagnostics.js';
 import { postgresDialect } from './dialect.js';
 import { ConnectionError, errorMessageModesDiverged, explainConnectionLoss, PipelineError, registerClientErrorMessageMode, runWithErrorMessageMode, setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
+import { normalizeGlobalFilters, tableAccessorName } from './global-filters-config.js';
+import { CLIENT_LOG_CONTEXT, logTo, resolveLogger } from './logger.js';
+import { hasRelationFields } from './nested-write.js';
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface, } from './query/index.js';
-import { markTurbineParser, ownLookup, quoteIdent, registerUtcTemporalParsers, suggestKey, warnParserOverwrite, } from './query/utils.js';
+import { assertNoLockInAutocommitPipeline } from './query/row-lock.js';
+import { commentDeferred, resolveSqlComment } from './query/sql-comment.js';
+import { resolveStreamIdleTimeout } from './query/stream-idle.js';
+import { asQueryInterface, TABLE_METHODS } from './query/table-client.js';
+import { ownLookup, quoteIdent, registerUtcTemporalParsers, sendCancelRequest, suggestKey, warnParserOverwrite, } from './query/utils.js';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 import { currentQueryTag, deferredIdentity, emitStatementEvent, rawIdentity, resultRowCount, runReportedStatement, runWithQueryTag, } from './query-events.js';
 import { createSubscription, validateChannel, } from './realtime.js';
-import { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
+import { parseInt8, rawClientOf, typedQueryPool } from './supplied-pool-types.js';
+import { commitTransaction, rolledBackError, TRANSACTION_STATE, TransactionState, unawaitedWorkError, } from './transaction-state.js';
+import { buildTypedSql, TypedSqlQuery, utcDateParams } from './typed-sql.js';
 export async function withRetry(fn, options) {
     const maxAttempts = options?.maxAttempts ?? 3;
     const baseDelay = options?.baseDelay ?? 50;
@@ -103,11 +113,17 @@ const TURBINE_CONFIG_KEYS = {
     idleTimeoutMillis: true,
     connectionTimeoutMillis: true,
     logging: true,
+    logger: true,
+    diagnostics: true,
     defaultLimit: true,
     warnOnUnlimited: true,
     utcTimestamps: true,
     temporalInfinity: true,
     planCacheMode: true,
+    statementTimeoutMs: true,
+    maxLifetimeSeconds: true,
+    streamIdleTimeoutMs: true,
+    sqlComment: true,
     scopedConnect: true,
     relationLoadStrategy: true,
     stableRelationOrder: true,
@@ -155,8 +171,7 @@ function suggestConfigKey(key) {
     return suggestKey(key, CONFIG_KEY_SET);
 }
 /**
- * Dev-mode notice for a key on the config object that is not part of the config
- * surface.
+ * Notice for a key on the config object that is not part of the config surface.
  *
  * An unknown key is silently ignored (JavaScript objects have no schema), which
  * makes a typo or a wrong guess indistinguishable from a broken feature: a
@@ -168,12 +183,10 @@ function suggestConfigKey(key) {
  * turbine that passes a key this version has not heard of must keep running,
  * and the whole check is wrapped so that a hostile / exotic config object
  * (a Proxy whose `ownKeys` throws) cannot take down the constructor either.
- * Dev-only (`NODE_ENV !== 'production'`) and once per key per process, like the
- * other advisory diagnostics.
+ * Always on, whatever `diagnostics` says: an ignored option is ignored in
+ * production too, and the line fires once per key per process.
  */
-function warnUnknownConfigKeys(config) {
-    if (process.env.NODE_ENV === 'production')
-        return;
+function warnUnknownConfigKeys(config, logger) {
     try {
         for (const key of Object.keys(config)) {
             if (CONFIG_KEY_SET.has(key) || NON_CONFIG_KEYS.has(key))
@@ -181,8 +194,8 @@ function warnUnknownConfigKeys(config) {
             if (!shouldWarnOnce(WARN_NS.unknownConfigKey, key))
                 continue;
             const suggestion = suggestConfigKey(key);
-            console.warn(`[turbine] Unknown option "${key}" in the config passed to TurbineClient, it is ignored.` +
-                (suggestion ? ` Did you mean "${suggestion}"?` : ''));
+            logTo(logger, 'warn', `Unknown option "${key}" in the config passed to TurbineClient, it is ignored.` +
+                (suggestion ? ` Did you mean "${suggestion}"?` : ''), { code: 'unknown-config-key', key, ...(suggestion ? { suggestion } : {}) });
         }
     }
     catch {
@@ -329,20 +342,6 @@ const ISOLATION_LEVELS = Object.assign(Object.create(null), {
     RepeatableRead: 'REPEATABLE READ',
     Serializable: 'SERIALIZABLE',
 });
-/**
- * Resolve a requested isolation level, REFUSING anything not in the map.
- *
- * A miss used to yield `undefined`, which `beginStatement` renders as a plain
- * `BEGIN`. So `isolationLevel: 'serializable'` (wrong case) asked for
- * SERIALIZABLE and silently got READ COMMITTED, which is the worst available
- * outcome for this option: the caller believes it has a guarantee it does not
- * have, and the workload that depended on it produces wrong data with no error.
- *
- * The TypeScript union on `TransactionOptions.isolationLevel` does not prevent
- * this. It is not enforced for a JavaScript consumer of a published package, for
- * a value read from config or an environment variable, or across any `as`.
- * Throwing costs a caller who was already broken one clear error.
- */
 /**
  * Run a transaction-control statement (BEGIN / COMMIT / ROLLBACK) with the same
  * error translation every other query boundary gets.
@@ -358,20 +357,101 @@ const ISOLATION_LEVELS = Object.assign(Object.create(null), {
  * loops, and a loop keyed on it would never fire for the commit-time conflicts
  * that are the main reason to run SERIALIZABLE at all.
  */
-async function runTxControl(client, sql) {
+async function runTxControl(client, sql, params) {
     try {
-        await client.query(sql);
+        await client.query(sql, params);
     }
     catch (err) {
         throw wrapPgError(err);
     }
 }
+/**
+ * Refuse anything in a batch that is not a deferred query, before any of it
+ * runs.
+ *
+ * The array forms take the descriptors `build*()` returns. Prisma's array form
+ * takes promises instead, so code ported from it passes `db.users.create(...)`,
+ * whose query has ALREADY started on its own connection, outside any
+ * transaction, by the time the array exists. That cannot be undone here, so
+ * the error says so and names the builder to use instead. The promise's own
+ * rejection is observed, so this refusal is the error the caller sees rather
+ * than an unhandled rejection from a query nobody awaits.
+ */
+function assertDeferredQueries(queries, api, unit) {
+    queries.forEach((q, i) => {
+        if (q !== null &&
+            (typeof q === 'object' || typeof q === 'function') &&
+            typeof q.then === 'function') {
+            Promise.resolve(q).catch(() => { });
+            throw new ValidationError(`${api}: item ${i} is a Promise. Its query started running on its own the moment it was created, ` +
+                `outside this ${unit}, and may already have committed. Pass the deferred form instead, built with ` +
+                '`build*()`: `db.users.buildCreate(...)` rather than `db.users.create(...)` (likewise `buildUpdate`, ' +
+                '`buildDelete`, `buildUpsert`, `buildFindMany`).' +
+                (unit === 'transaction' ? ' Or use the callback form, `$transaction(async (tx) => { ... })`.' : ''));
+        }
+        const dq = q;
+        if (!dq || typeof dq !== 'object' || typeof dq.sql !== 'string' || typeof dq.transform !== 'function') {
+            throw new ValidationError(`${api}: item ${i} is not a deferred query. Build each item with a \`build*()\` method, ` +
+                'for example `db.users.buildCreate({ data })` or `db.posts.buildCount({ where })`.');
+        }
+    });
+}
+/** The PG* variables pg reads for a connection target when its config leaves the field unset. */
+const PG_ENV_TARGETS = ['PGHOST', 'PGPORT', 'PGDATABASE', 'PGUSER'];
+/** A non-empty environment variable, or undefined (also where `process` does not exist). */
+function pgEnv(name) {
+    return (typeof process !== 'undefined' ? process.env?.[name] : undefined) || undefined;
+}
+/**
+ * Whether an owned pool's config names a database at all: a connection
+ * string, any host setting, DATABASE_URL (unless an explicit, empty
+ * `connectionString` suppresses it, as the pool branch does), or a PG*
+ * variable pg will read.
+ */
+function hasDatabaseTarget(config) {
+    if (config.connectionString)
+        return true;
+    if (config.host != null ||
+        config.port != null ||
+        config.database != null ||
+        config.user != null ||
+        config.password != null) {
+        return true;
+    }
+    if (config.connectionString == null && pgEnv('DATABASE_URL'))
+        return true;
+    return PG_ENV_TARGETS.some((name) => pgEnv(name) !== undefined);
+}
+/**
+ * The pool of a client that was given no database: every query and checkout
+ * rejects with a {@link ConnectionError} naming the fix, and `disconnect()`
+ * succeeds. Building SQL never touches the pool, so it still works.
+ */
+function unconfiguredPool(emptyConnectionString) {
+    const fail = () => Promise.reject(new ConnectionError('No database configured: ' +
+        (emptyConnectionString
+            ? "`connectionString` is an empty string, which names no database (often `process.env.DATABASE_URL ?? ''` " +
+                'evaluated before DATABASE_URL was loaded). '
+            : 'this client was given no `connectionString`, `pool` or host settings, and the DATABASE_URL environment ' +
+                'variable is not set. ') +
+        'turbine-orm does not read `.env` files: load yours before the app starts (`node --env-file=.env app.js`, ' +
+        'or `process.loadEnvFile()` on Node 20.12 and later), or pass `connectionString` explicitly.'));
+    return { query: fail, connect: fail, end: async () => { }, on: () => { } };
+}
+/**
+ * Resolve a requested isolation level, REFUSING anything not in the map.
+ *
+ * A miss rendered as a plain `BEGIN` would be the worst outcome for this
+ * option: `isolationLevel: 'serializable'` (wrong case) would ask for
+ * SERIALIZABLE and silently get READ COMMITTED. The TypeScript union does not
+ * prevent it for a JavaScript caller, a value read from config, or any `as`.
+ */
 function resolveIsolationLevel(level) {
     if (level === undefined)
         return undefined;
     const sql = ownLookup(ISOLATION_LEVELS, level);
     if (sql === undefined) {
-        throw new ValidationError(`$transaction: unknown isolationLevel ${JSON.stringify(level)}. ` +
+        throw new ValidationError(`$transaction: unknown isolationLevel ${describeValue(level)}. ` +
             `Expected one of: ${Object.keys(ISOLATION_LEVELS).join(', ')} (case-sensitive).`);
     }
     return sql;
@@ -384,34 +464,274 @@ function resolveIsolationLevel(level) {
  */
 const GUC_NAME_REGEX = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
 /**
- * The read-only `QueryInterface` operations that a read-replica setup may route
- * to a replica pool. Every other method (all writes, plus internals) stays on
- * the primary. Kept as a Set so the routing proxy's `get` trap is O(1).
+ * How long a transaction being abandoned (timed out, failed, or returned with
+ * work still running) gives its in-flight statement to answer a cancel
+ * request, and its ROLLBACK to answer, before the connection is destroyed
+ * instead of reused.
+ */
+const TX_ABORT_GRACE_MS = 2000;
+/** Default {@link TurbineConfig.maxLifetimeSeconds} on pools Turbine opens. */
+const DEFAULT_MAX_LIFETIME_SECONDS = 1800;
+/**
+ * A value as an error message should quote it. `JSON.stringify` writes `NaN` and
+ * `Infinity` as `null`, throws on a bigint, and returns `undefined` for a symbol
+ * or a function, so a message built from it can name a value the caller never
+ * passed.
+ */
+function describeValue(value) {
+    switch (typeof value) {
+        case 'string':
+            return JSON.stringify(value);
+        case 'bigint':
+            return `${value}n`;
+        case 'symbol':
+            return value.toString();
+        case 'function':
+            return 'a function';
+        case 'object':
+            return value === null ? 'null' : Array.isArray(value) ? 'an array' : 'an object';
+        default:
+            return String(value);
+    }
+}
+/**
+ * `allowBuiltinSettings` as a lower-cased set (PostgreSQL folds setting names).
+ * Each entry must be a plain un-dotted setting name; anything else is E003.
  */
+function resolveBuiltinSettingsAllowlist(value) {
+    if (value === undefined)
+        return new Set();
+    if (!Array.isArray(value)) {
+        throw new ValidationError(`$transaction: allowBuiltinSettings must be an array of setting names, received ${typeof value}.`);
+    }
+    const names = new Set();
+    for (const name of value) {
+        if (typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+            throw new ValidationError(`$transaction: allowBuiltinSettings entry ${describeValue(name)} is not a PostgreSQL setting name ` +
+                '(a plain identifier such as "statement_timeout"). Namespaced custom settings need no entry.');
+        }
+        names.add(name.toLowerCase());
+    }
+    return names;
+}
+/**
+ * SQLSTATEs with which the server refuses a `set_config`, and what each means
+ * for the caller. A function of the setting where the cause depends on it: the
+ * same SQLSTATE says "no such role" for `role` and "unreadable duration" for
+ * `statement_timeout`.
+ */
+const SESSION_SETTING_REFUSALS = Object.assign(Object.create(null), {
+    '22023': (setting) => setting === 'role' || setting === 'session_authorization'
+        ? 'the value is not valid for this setting (the role must exist)'
+        : 'the value is not valid for this setting',
+    '42704': () => 'the server has no setting by that name',
+    '42501': () => 'the database role is not allowed to change it',
+    '55P02': () => 'it cannot be changed after the connection has started',
+});
 /**
- * Operations that may be served by a read replica.
+ * Apply one `sessionContext` entry. A refusal by the server names the setting
+ * that caused it rather than reading as a column or type error; the server's
+ * own message (which may contain the value) stays on `cause`.
+ */
+async function applySessionSetting(client, setting) {
+    try {
+        await client.query(setting.sql, setting.params);
+    }
+    catch (err) {
+        const code = err?.code;
+        const describe = typeof code === 'string' ? SESSION_SETTING_REFUSALS[code] : undefined;
+        if (describe === undefined)
+            throw wrapPgError(err);
+        throw new ValidationError(`sessionContext["${setting.name}"] was refused by the server: ${describe(setting.name.toLowerCase())} (SQLSTATE ${code}). ` +
+            'The transaction was rolled back before your callback ran.', { cause: err });
+    }
+}
+/** A non-negative safe integer config value, or `undefined` when unset. Anything else is E003. */
+function resolveNonNegativeInteger(value, name, unit) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new ValidationError(`Invalid ${name}: ${typeof value === 'string' ? JSON.stringify(value) : String(value)}. Expected a ` +
+            `non-negative whole number of ${unit}.`);
+    }
+    return value;
+}
+/**
+ * Refuse a dialect with no `capabilities` object (E003): every code path asks
+ * it what the engine can do, so a hand-built dialect without one would fail on
+ * its first query with a TypeError instead of here.
+ */
+function assertDialectCapabilities(dialect) {
+    const capabilities = dialect.capabilities;
+    if (typeof capabilities === 'object' && capabilities !== null)
+        return;
+    throw new ValidationError(`The dialect "${String(dialect.name)}" has no \`capabilities\` object, which says what the engine can do. ` +
+        'Build it from an engine dialect (`{ ...postgresDialect, name, capabilities: { ... } }`) and state every ' +
+        'EngineCapabilities key.');
+}
+/**
+ * The statement that opens a transaction, read-only when asked. PostgreSQL and
+ * MySQL both accept `READ ONLY` after their own BEGIN form (`BEGIN [ISOLATION
+ * LEVEL x] READ ONLY`, `[SET TRANSACTION ISOLATION LEVEL x; ]START TRANSACTION
+ * READ ONLY`); the other engines have no read-only transaction.
+ */
+function beginStatementFor(dialect, isolationSql, readOnly) {
+    const begin = dialect.beginStatement(isolationSql);
+    if (!readOnly)
+        return begin;
+    if (dialect.capabilities.readOnlyTransactions)
+        return `${begin} READ ONLY`;
+    throw new UnsupportedFeatureError('$transaction({ readOnly: true })', dialect.name, 'This engine has no read-only transaction mode. Drop the option, or enforce read-only access with a ' +
+        'database role that has no write privileges.');
+}
+/** `readOnly` as a boolean; anything but a boolean or `undefined` is E003. */
+function resolveReadOnly(value) {
+    if (value === undefined || value === false)
+        return false;
+    if (value === true)
+        return true;
+    throw new ValidationError(`$transaction: readOnly must be true or false, received ${describeValue(value)}.`);
+}
+/** Whether `pending` settles (either way) within `ms`. */
+async function settlesWithin(pending, ms) {
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), ms);
+    });
+    try {
+        return await Promise.race([
+            pending.then(() => true, () => true),
+            late,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Stop a transaction that will not commit, on the server and now: cancel the
+ * statement it is running (the protocol's CancelRequest, which also reaches the
+ * right backend through a pooler), wait for it to answer, then ROLLBACK, which
+ * releases every lock the transaction holds.
  *
- * This is a hand-maintained list of names, so it drifts the moment a read
- * method is added to `QueryInterface` and not added here. The failure is
- * SILENT and directional: the missing operation keeps working, it just runs on
- * the PRIMARY, so no test fails and no user sees an error, only a busier
- * primary. `findManyStreamBatches` was added and missed exactly this way.
- * `src/test/read-operations-drift.test.ts` closes the loop mechanically.
+ * Closing the socket alone does not do that. PostgreSQL notices a closed
+ * client only when it next writes to it, so a backend waiting on a lock keeps
+ * the transaction, and every lock it already took, until that lock clears.
+ *
+ * Resolves `true` when the connection is rolled back and reusable, `false` when
+ * it is not (the cancel could not be sent, the statement or the ROLLBACK did not
+ * answer within {@link TX_ABORT_GRACE_MS}, or the ROLLBACK failed); the caller
+ * then destroys it. Call after `state.end()`, so nothing new is sent meanwhile.
+ */
+async function rollbackOnServer(client, state, dialect) {
+    if (state.running) {
+        if (!(await sendCancelRequest(client, TX_ABORT_GRACE_MS)))
+            return false;
+        if (!(await state.whenIdle(TX_ABORT_GRACE_MS)))
+            return false;
+    }
+    let failed = false;
+    const rollback = client.query(dialect.rollbackStatement()).catch(() => {
+        failed = true;
+    });
+    return (await settlesWithin(rollback, TX_ABORT_GRACE_MS)) && !failed;
+}
+/** `rawUnsafe` takes statement text; a tagged-template call or a non-string is E003. */
+function assertSqlText(text, api) {
+    if (typeof text === 'string' && text.trim() !== '')
+        return;
+    throw new ValidationError(Array.isArray(text)
+        ? `${api} takes the statement as a string, not as a tagged template. Use raw\`...\` or sql\`...\` for a ` +
+            'template, whose values are bound for you.'
+        : `${api} takes the statement text as a non-empty string, received ${text === null ? 'null' : typeof text}.`);
+}
+/**
+ * The connection `transaction(fn)` and `tx.$connection()` hand out: the
+ * checked-out client, with every statement routed through the transaction's
+ * state, so one issued after the transaction settled is refused rather than
+ * run on a connection that is back in the pool, and transaction-control SQL
+ * (`COMMIT`, `BEGIN`, ...) is refused rather than ending the transaction behind
+ * the state that tracks it.
+ *
+ * What would take the connection away is refused too: `release` (the
+ * transaction returns it itself), `end` and `connect`, and the driver's
+ * `connection` (the wire-level object, whose writes bypass every check here) is
+ * hidden. Everything else is the driver client's own.
+ */
+function closableRawClient(client, state, scope = state.rootScope, api = 'transaction()') {
+    // The refusals name the API the caller used: a `tx.$connection()` caller
+    // never called `transaction()`.
+    const who = api === 'transaction()' ? 'transaction(): the callback' : '$connection(): the $transaction callback';
+    const target = client;
+    const send = target.query;
+    const query = (...args) => {
+        const first = args[0];
+        const text = typeof first === 'string' ? first : first?.text;
+        // Callback form and submittables (cursors, COPY streams) answer through
+        // their own channel, not a promise: checked, then passed straight through.
+        if (typeof args[args.length - 1] === 'function' ||
+            typeof first?.submit === 'function') {
+            state.assertOpen();
+            state.screenRaw(text);
+            return send.apply(client, args);
+        }
+        return state.runRaw(text, () => send.apply(client, args), scope);
+    };
+    const release = () => {
+        throw new ValidationError(`${who} must not release its client; the transaction releases it after COMMIT or ROLLBACK.`);
+    };
+    const refuse = (verb) => {
+        return () => {
+            throw new ValidationError(`${who} must not ${verb} its client; the transaction owns the connection and ` +
+                'returns it to the pool after COMMIT or ROLLBACK.');
+        };
+    };
+    const refused = new Map([
+        ['end', refuse('end')],
+        ['connect', refuse('connect')],
+    ]);
+    const bound = new Map();
+    return new Proxy(target, {
+        has(t, prop) {
+            return prop === 'connection' ? false : Reflect.has(t, prop);
+        },
+        get(t, prop) {
+            if (prop === 'query')
+                return query;
+            if (prop === 'release')
+                return release;
+            if (prop === 'connection')
+                return undefined;
+            const refusal = refused.get(prop);
+            if (refusal !== undefined)
+                return refusal;
+            const value = Reflect.get(t, prop, t);
+            if (typeof value !== 'function')
+                return value;
+            let fn = bound.get(prop);
+            if (fn === undefined) {
+                fn = value.bind(t);
+                bound.set(prop, fn);
+            }
+            return fn;
+        },
+    });
+}
+/**
+ * Operations that may be served by a read replica: the `read` entries of
+ * {@link TABLE_METHODS}. Every other method (writes, `build*`, internals) stays
+ * on the primary. A Set so the routing proxy's `get` trap is O(1).
+ *
+ * Derived, not listed, because a hand-kept list drifts SILENTLY: a read method
+ * missing here keeps working on the primary, so no test fails. A new public
+ * QueryInterface method cannot compile until it is classified in TABLE_METHODS.
+ * `src/test/read-operations-drift.test.ts` is the run-time check.
  *
  * Exported for that test only.
  */
-export const READ_OPERATIONS = new Set([
-    'findMany',
-    'findFirst',
-    'findUnique',
-    'findFirstOrThrow',
-    'findUniqueOrThrow',
-    'count',
-    'aggregate',
-    'groupBy',
-    'findManyStream',
-    'findManyStreamBatches',
-]);
+export const READ_OPERATIONS = new Set(Object.entries(TABLE_METHODS)
+    .filter(([, kind]) => kind === 'read')
+    .map(([name]) => name));
 /**
  * Internal marker on the config object that tells the `TurbineClient`
  * constructor to build a lightweight "primary-only" view sharing an existing
@@ -426,6 +746,10 @@ const PRIMARY_VIEW = Symbol('turbine.primaryView');
  * A transaction-scoped client that provides the same table accessor API as TurbineClient.
  * All queries run on a dedicated connection within a BEGIN/COMMIT block.
  * Supports nested transactions via SAVEPOINTs.
+ *
+ * Closed when its transaction settles (commit, rollback, timeout, error): every
+ * later call through it throws `ValidationError` (E003) instead of running on a
+ * connection that is back in the pool and may belong to another request.
  */
 export class TransactionClient {
     client;
@@ -434,9 +758,19 @@ export class TransactionClient {
     queryOptions;
     sourcePool;
     tableCache = new Map();
-    savepointCounter = 0;
     /** Active SQL dialect, owns savepoint keywords and raw-SQL placeholders. */
     dialect;
+    /** Open/closed state, first failure and savepoint blocks, shared by everything this client hands out. */
+    state;
+    /**
+     * Where in the transaction this handle sits: the transaction itself, or the
+     * nested block whose callback received it. Statements carry it, so one issued
+     * through an outer handle from inside a block can be told from one issued
+     * through the block's own.
+     */
+    scope;
+    /** What {@link $connection} hands out, built on first use. */
+    connectionHandle;
     constructor(client, schema, middlewares, queryOptions, 
     /**
      * The parent pool this transaction runs on. Only its `readonly` and
@@ -447,16 +781,26 @@ export class TransactionClient {
      * (emitting join PowQL a pre-0.13 engine rejects). Undefined / absent flags
      * for a plain pg pool leave the proxy unchanged.
      */
-    sourcePool) {
+    sourcePool, 
+    /**
+     * The state of the transaction this client belongs to. `$transaction`
+     * passes the one it opened, which also turns on per-write savepoints for
+     * multi-statement writes. Omitted for Turbine's own implicit transactions.
+     */
+    state, 
+    /** The nested block this handle belongs to; omitted for the transaction's own handle. */
+    scope) {
         this.client = client;
         this.schema = schema;
         this.middlewares = middlewares;
         this.queryOptions = queryOptions;
         this.sourcePool = sourcePool;
         this.dialect = queryOptions?.dialect ?? postgresDialect;
+        this.state = state ?? new TransactionState(client, this.dialect);
+        this.scope = scope ?? this.state.rootScope;
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
-            const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+            const camelName = tableAccessorName(tableName);
             if (!(camelName in this)) {
                 Object.defineProperty(this, camelName, {
                     get: () => this.table(tableName),
@@ -477,43 +821,121 @@ export class TransactionClient {
             const txPool = this.createTxPool();
             const txOpts = { ...this.queryOptions, _txScoped: true };
             qi = txOpts.queryInterfaceFactory
-                ? txOpts.queryInterfaceFactory(txPool, name, this.schema, this.middlewares, txOpts)
+                ? asQueryInterface(txOpts.queryInterfaceFactory(txPool, name, this.schema, this.middlewares, txOpts))
                 : new QueryInterface(txPool, name, this.schema, this.middlewares, txOpts);
+            if (this.state.savepointWrites)
+                savepointMultiStatementWrites(qi, this.schema.tables[name], this.state);
             this.tableCache.set(name, qi);
         }
         return qi;
     }
     /**
-     * Execute a nested transaction via SAVEPOINT.
-     * If the inner function throws, only the savepoint is rolled back.
+     * The driver connection this transaction runs on, for code that needs one:
+     * another library's query function, a COPY stream, a driver feature Turbine
+     * does not wrap. Statements sent on it run inside this transaction.
+     *
+     * - It closes with the transaction: a statement sent after COMMIT or
+     *   ROLLBACK is refused with `ValidationError` (E003) instead of running on a
+     *   connection that is back in the pool.
+     * - `release()` is refused. The transaction returns the connection.
+     * - COMMIT, ROLLBACK, BEGIN, SAVEPOINT, RELEASE and SET TRANSACTION are
+     *   refused with `ValidationError` (E003): the transaction ends itself, and
+     *   Turbine would then commit or roll back a transaction that is no longer
+     *   open. Use `tx.$transaction` for a savepoint.
+     * - `end()` and `connect()` are refused like `release()`, and the driver's
+     *   `connection` object is not reachable through it.
+     * - Its queries use the driver's own parsers. On a pool you supplied, that is
+     *   your parser configuration, not Turbine's int8 and UTC readings.
+     *
+     * Typed as the driver-neutral client. For the pg-only surface, cast:
+     * `tx.$connection() as unknown as PoolClient`.
+     *
+     * Throws `UnsupportedFeatureError` (E017) where no driver connection backs
+     * the transaction: PowDB, and a stateless HTTP driver.
      */
-    async $transaction(fn) {
-        const savepointName = `sp_${++this.savepointCounter}`;
-        await this.client.query(this.dialect.savepointStatement(savepointName));
-        try {
-            const result = await fn(this);
-            await this.client.query(this.dialect.releaseSavepointStatement(savepointName));
-            return result;
+    $connection() {
+        this.state.assertOpen();
+        if (this.connectionHandle)
+            return this.connectionHandle;
+        const raw = rawClientOf(this.client);
+        const driver = this.dialect.capabilities.connectionDriver;
+        if (driver === 'none') {
+            throw new UnsupportedFeatureError('tx.$connection()', this.dialect.name, 'A PowDB transaction has no driver connection to hand out. Run PowQL inside it with `tx.rawUnsafe(text, ...values)`.');
         }
-        catch (err) {
-            await this.client.query(this.dialect.rollbackToSavepointStatement(savepointName));
-            throw err;
+        if (driver === 'pg-compatible' && typeof raw.on !== 'function') {
+            throw new UnsupportedFeatureError('tx.$connection()', this.dialect.name, 'The pool returned a client with no event support, as a stateless HTTP driver does, so there is no ' +
+                'connection to hand out. Use `tx.raw` / `tx.rawUnsafe`, or a TCP pool.');
         }
+        this.connectionHandle = closableRawClient(raw, this.state, this.scope, '$connection()');
+        return this.connectionHandle;
     }
     /**
-     * Execute a raw SQL query within this transaction.
+     * Execute a nested transaction via SAVEPOINT.
+     *
+     * If the inner function throws, only the savepoint is rolled back. Blocks
+     * started side by side (`Promise.all`) run one after another, because
+     * savepoints are a stack on the connection and a rollback in one would
+     * otherwise undo a sibling that already reported success.
+     *
+     * The callback receives a `tx` of its own, bound to the block. Use it for the
+     * work inside the block: a statement through the OUTER `tx` from inside the
+     * block would run in the block's savepoint and be undone with it, so it is
+     * refused with `ValidationError` (E003).
+     */
+    async $transaction(fn) {
+        return this.state.withBlock((scope) => fn(this.inScope(scope)), this.scope);
+    }
+    /** A handle on the same transaction bound to nested block `scope`. */
+    inScope(scope) {
+        return new TransactionClient(this.client, this.schema, this.middlewares, this.queryOptions, this.sourcePool, this.state, scope);
+    }
+    /**
+     * Execute a raw SQL query within this transaction, as a tagged template:
+     * every `${value}` is sent as a bound parameter.
      */
     async raw(strings, ...values) {
-        let sql = '';
-        strings.forEach((str, i) => {
-            sql += str;
-            if (i < values.length) {
-                sql += this.dialect.paramPlaceholder(i + 1);
-            }
-        });
-        const result = await runReportedStatement(this.queryOptions?._onQuery, rawIdentity('raw'), sql, values, () => this.client.query(sql, values), wrapPgError);
+        const { sql, params } = buildTypedSql(strings, values, this.dialect, 'raw');
+        return this.runRaw(sql, params, 'raw');
+    }
+    /**
+     * Execute SQL text built at runtime within this transaction. See
+     * {@link TurbineClient.rawUnsafe}: nothing in `text` is escaped, so it must
+     * never contain untrusted input. Values go in `values`, referenced as `$1`,
+     * `$2`, ... (the engine's own placeholders on other engines).
+     */
+    async rawUnsafe(text, ...values) {
+        assertSqlText(text, 'rawUnsafe');
+        return this.runRaw(text, values, 'rawUnsafe');
+    }
+    /**
+     * Typed raw SQL on this transaction's connection, like
+     * {@link TurbineClient.sql}: await it for `T[]`, or call `.one()` /
+     * `.scalar()`. Refused, like every other `tx` call, once the transaction has
+     * settled.
+     */
+    sql(strings, ...values) {
+        this.state.assertOpen();
+        const { sql, params: bound } = buildTypedSql(strings, values, this.dialect);
+        const params = this.rawParams(bound, 'sql');
+        const state = this.state;
+        const client = this.client;
+        const scope = this.scope;
+        const pool = {
+            query: (text, vals) => state.runRaw(text, () => client.query(text, vals), scope),
+        };
+        return new TypedSqlQuery(pool, sql, params, false, undefined, this.queryOptions?._onQuery);
+    }
+    async runRaw(sql, values, action) {
+        const params = this.rawParams(values, action);
+        const result = await this.state.runRaw(sql, () => runReportedStatement(this.queryOptions?._onQuery, rawIdentity(action), sql, params, () => this.client.query(sql, params), wrapPgError), this.scope);
         return result.rows;
     }
+    /** Bound Dates as UTC text on a PostgreSQL client reading temporal types as UTC. */
+    rawParams(params, api) {
+        return this.dialect.capabilities.utcTimestampRewrite && this.queryOptions?.utcTimestamps !== false
+            ? utcDateParams(params, api)
+            : params;
+    }
     /**
      * @internal The `turbine-orm/prisma-compat` adapter's transaction seam. NOT
      * application API: use {@link raw}, whose tagged template makes concatenating
@@ -541,7 +963,8 @@ export class TransactionClient {
      * passes `'$queryRaw'` / `'$executeRaw'` ...; default `'rawQuery'`).
      */
     async rawQuery(text, params = [], action = 'rawQuery') {
-        const result = await runReportedStatement(this.queryOptions?._onQuery, rawIdentity(action), text, params, () => this.client.query(text, params), wrapPgError);
+        const bound = this.rawParams(params, action);
+        const result = await this.state.runRaw(text, () => runReportedStatement(this.queryOptions?._onQuery, rawIdentity(action), text, bound, () => this.client.query(text, bound), wrapPgError), this.scope);
         return { rows: result.rows, rowCount: result.rowCount };
     }
     /**
@@ -551,28 +974,40 @@ export class TransactionClient {
      *
      * pg driver errors thrown by queries are translated into typed Turbine
      * errors via wrapPgError so transaction-scoped queries surface the same
-     * typed errors as pool-scoped queries.
+     * typed errors as pool-scoped queries. Every statement passes through the
+     * transaction state, which refuses it once the transaction has settled.
      */
     createTxPool() {
         const client = this.client;
+        const state = this.state;
+        const scope = this.scope;
+        const query = (textOrConfig, values) => state.run(async () => {
+            try {
+                if (typeof textOrConfig === 'string') {
+                    return await client.query(textOrConfig, values);
+                }
+                // Object form for prepared statements: { name, text, values }
+                // A driver client accepts it, but the two-argument `query` in the
+                // PgCompatPoolClient contract does not describe it, so we cast.
+                return await client.query(textOrConfig);
+            }
+            catch (err) {
+                throw wrapPgError(err);
+            }
+        }, scope);
         // Return a minimal pool-compatible object that routes queries
         // through the transaction client
         const txPool = {
-            query: async (textOrConfig, values) => {
-                try {
-                    if (typeof textOrConfig === 'string') {
-                        return await client.query(textOrConfig, values);
-                    }
-                    // Object form for prepared statements: { name, text, values }
-                    // A driver client accepts it, but the two-argument `query` in the
-                    // PgCompatPoolClient contract does not describe it, so we cast.
-                    return await client.query(textOrConfig);
-                }
-                catch (err) {
-                    throw wrapPgError(err);
-                }
+            query,
+            // The transaction's connection is not this pool's to lend: a "checkout"
+            // runs on it through the same guarded `query`, and releasing it is a
+            // no-op, so nothing reached through the pool can hand the connection back
+            // to the real pool while the transaction still holds it.
+            connect: async () => {
+                state.assertOpen();
+                return { query, release: () => { } };
             },
-            connect: () => Promise.resolve(client),
+            [TRANSACTION_STATE]: state,
         };
         // Carry the parent pool's PowDB-only flags through so a transaction-scoped
         // PowqlInterface reads the same read-only guard and capabilities it would
@@ -584,6 +1019,47 @@ export class TransactionClient {
         return txPool;
     }
 }
+/**
+ * Give each multi-statement write on a transaction-scoped accessor its own
+ * savepoint: `create` / `update` carrying nested relation writes, and an
+ * `upsert` that looks the row up first.
+ *
+ * Joining the caller's transaction statement by statement, a failure raised
+ * part way through (a nested `connect` that finds nothing, a validation error
+ * found mid-walk) would leave the statements before it in place, and a caller
+ * that caught the error and went on would commit half of the write. In its own
+ * savepoint the write is all or nothing, and the caller's transaction
+ * continues either way.
+ *
+ * Installed as own methods on the accessor this transaction created and owns,
+ * so a single-statement write pays one property lookup and a shape check.
+ */
+function savepointMultiStatementWrites(qi, meta, state) {
+    if (!meta)
+        return;
+    const target = qi;
+    const nestedData = (args) => {
+        const data = args?.data;
+        return data !== null && typeof data === 'object' && hasRelationFields(data, meta);
+    };
+    const lookupUpsert = (args) => {
+        const needsLookup = qi.upsertNeedsLookup;
+        return typeof needsLookup === 'function' && args !== undefined && needsLookup.call(qi, args);
+    };
+    const wrap = (method, multiStatement) => {
+        const original = target[method];
+        if (typeof original !== 'function')
+            return;
+        Object.defineProperty(qi, method, {
+            value: (args) => multiStatement(args) ? state.withSavepoint(() => original.call(qi, args)) : original.call(qi, args),
+            configurable: true,
+            writable: true,
+        });
+    };
+    wrap('create', nestedData);
+    wrap('update', nestedData);
+    wrap('upsert', lookupUpsert);
+}
 // ---------------------------------------------------------------------------
 // TurbineClient
 // ---------------------------------------------------------------------------
@@ -601,6 +1077,13 @@ export class TurbineClient {
      * `db.pool as unknown as Pool`.
      */
     pool;
+    /**
+     * The pool Turbine's own statements go through: {@link pool}, or for a
+     * caller-supplied PostgreSQL pool a view of it whose queries carry Turbine's
+     * int8 and temporal parsers (see supplied-pool-types.ts). `pool` stays the
+     * caller's object, and queries the caller runs on it keep their parsers.
+     */
+    queryPool;
     /** The schema metadata this client was built from */
     schema;
     static int8ParserRegistered = false;
@@ -628,6 +1111,10 @@ export class TurbineClient {
      */
     static utcTimestampParsersRegistered = false;
     logging;
+    /** Where this client's log lines go (the `logger` option, else console). */
+    logger;
+    /** The `diagnostics` option, resolved once at construction. */
+    diagnostics;
     /** Active SQL dialect, owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
     dialect;
     /** Validated `plan_cache_mode` to pin on every owned connection, or undefined to issue nothing. */
@@ -636,6 +1123,10 @@ export class TurbineClient {
     middlewares = [];
     queryListeners = new Set();
     queryOptions;
+    /** The resolved `sqlComment` every accessor shares, for the batch paths that bypass them. */
+    get sqlCommenter() {
+        return this.queryOptions._sqlCommenter;
+    }
     errorMessagesSafe;
     /**
      * THIS client's error-message mode. Not the process default: see
@@ -652,6 +1143,10 @@ export class TurbineClient {
     ownsPool = true;
     /** Active LISTEN subscriptions, torn down on disconnect() so it never hangs */
     activeSubscriptions = new Set();
+    /** `$on('poolError')` / `$on('connectionLost')` listeners. */
+    poolListeners = { poolError: new Set(), connectionLost: new Set() };
+    /** What each pool Turbine opened has checked out, for `disconnect({ timeoutMs })`. */
+    checkoutWatches = [];
     /**
      * Read-replica pools in round-robin order. Empty when no replicas are
      * configured, in which case `table()` takes the original single-pool path.
@@ -681,19 +1176,23 @@ export class TurbineClient {
             const parent = seed.parent;
             this.schema = schema;
             this.logging = parent.logging;
+            this.logger = parent.logger;
+            this.diagnostics = parent.diagnostics;
             this.dialect = parent.dialect;
             this.errorMessagesSafe = parent.errorMessagesSafe;
             this.errorMessageMode = parent.errorMessageMode;
             this.queryParamsVisible = parent.queryParamsVisible;
             this.queryOptions = parent.queryOptions;
             this.middlewares = parent.middlewares; // shared reference: $use on parent flows through
+            this.poolListeners = parent.poolListeners;
             this.pool = parent.pool;
+            this.queryPool = parent.queryPool;
             this.ownsPool = false;
             this.replicaPools = [];
             this.ownedReplicaPools = [];
             this.replicaTableCaches = [];
             for (const tableName of Object.keys(schema.tables)) {
-                const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+                const camelName = tableAccessorName(tableName);
                 if (!(camelName in this)) {
                     Object.defineProperty(this, camelName, {
                         get: () => this.table(tableName),
@@ -731,15 +1230,38 @@ export class TurbineClient {
             }
             break;
         }
+        // The logger and the diagnostics mode are validated first, so every line
+        // below, the construction warnings included, reaches the caller's logger.
+        // NODE_ENV is read here and nowhere on a query path.
+        const logger = resolveLogger(config.logger);
+        const diagnostics = resolveDiagnostics(config.diagnostics);
         // Name any key on the config object that is not part of the config surface
-        // (dev only, once per key, never throws). See warnUnknownConfigKeys.
-        warnUnknownConfigKeys(config);
+        // (once per key, never throws). See warnUnknownConfigKeys.
+        warnUnknownConfigKeys(config, logger);
         // ALL config validation runs before ANY process-global side effect below.
         // A constructor that throws must leave the process exactly as it found it:
         // settling the process-global parser mode and then rejecting the config
         // would poison the next, valid, TurbineClient with a phantom conflict.
         const dialect = config.dialect ?? postgresDialect;
+        assertDialectCapabilities(dialect);
         const planCacheMode = TurbineClient.resolvePlanCacheMode(config.planCacheMode, dialect);
+        const statementTimeoutMs = TurbineClient.resolveStatementTimeout(config.statementTimeoutMs, dialect);
+        const maxLifetimeSeconds = resolveNonNegativeInteger(config.maxLifetimeSeconds, 'maxLifetimeSeconds', 'seconds');
+        const streamIdleTimeoutMs = resolveStreamIdleTimeout(config.streamIdleTimeoutMs, 'streamIdleTimeoutMs');
+        // A backend that injects its own query interface (PowDB) builds no SQL,
+        // so there is nothing for a comment to ride on: refused, not ignored.
+        const sqlComment = resolveSqlComment(config.sqlComment, logger, {
+            dialect: dialect.name,
+            preparesEveryStatement: dialect.capabilities.preparesEveryStatement,
+            buildsSql: config.queryInterfaceFactory === undefined,
+        });
+        // Keyed by table name, with every key checked against the schema: a
+        // filter under a name that matches no table would never be applied.
+        // A non-SQL backend (PowDB) injects its own query interface and checks
+        // its own filters; every SQL engine compiles each static filter here once,
+        // with this client's dialect, so a value the compiler refuses fails now.
+        const factory = config.queryInterfaceFactory;
+        const globalFilters = normalizeGlobalFilters(config.globalFilters, schema, factory === undefined ? { QueryInterface, dialect, utcTimestamps: config.utcTimestamps } : undefined);
         // Refuse a connection string that cannot address a database, before it
         // reaches pg's permissive parser and comes back one query later as a DNS
         // error about a fragment of itself. Only the strings this client will
@@ -793,16 +1315,14 @@ export class TurbineClient {
         // fork and rely on their own parser configuration, registration is
         // process-global, so flipping it because a string replica exists alongside
         // an external primary would silently change the external primary's parsing
-        // too. String replicas configured next to an external primary therefore
-        // inherit the caller's parser configuration (documented). Registration is
-        // constructor-gated by the static flags, so it happens at most once.
+        // too. With an external primary, Turbine's own queries carry the parsers
+        // per query instead, on the primary and on every replica (see typedPool).
+        // Registration is constructor-gated by the static flags, so it happens at
+        // most once.
         const ownsAnyPool = !config.pool;
         if (ownsAnyPool && !TurbineClient.int8ParserRegistered) {
-            warnParserOverwrite(20, 'int8');
-            pg.types.setTypeParser(20, markTurbineParser((val) => {
-                const n = Number(val);
-                return Number.isSafeInteger(n) ? n : val;
-            }));
+            warnParserOverwrite(20, 'int8', logger);
+            pg.types.setTypeParser(20, parseInt8);
             TurbineClient.int8ParserRegistered = true;
         }
         // Parse the zone-less temporal types (`timestamp` OID 1114, `date` OID
@@ -827,16 +1347,22 @@ export class TurbineClient {
         const wantUtcTimestamps = config.utcTimestamps !== false;
         TurbineClient.assertUtcTimestampsAgree(wantUtcTimestamps);
         if (ownsAnyPool && wantUtcTimestamps && !TurbineClient.utcTimestampParsersRegistered) {
-            registerUtcTemporalParsers();
+            registerUtcTemporalParsers(logger);
             TurbineClient.utcTimestampParsersRegistered = true;
         }
         TurbineClient.utcTimestampParserMode = wantUtcTimestamps;
         this.logging = config.logging ?? false;
+        this.logger = logger;
+        this.diagnostics = diagnostics;
         this.dialect = dialect;
         this.planCacheMode = planCacheMode;
         this.schema = schema;
         // Respect env var kill switch
         const envDisablePrepared = typeof process !== 'undefined' && process.env?.TURBINE_DISABLE_PREPARED === '1';
+        const pooler = config.pool ? undefined : TurbineClient.poolerEndpoint(config);
+        if (config.preparedStatements === true && pooler !== undefined) {
+            TurbineClient.warnPreparedOnPooler(pooler, logger);
+        }
         this.errorMessageMode = config.errorMessages ?? 'safe';
         this.errorMessagesSafe = this.errorMessageMode === 'safe';
         // Query-event param visibility. One derived boolean, so the two config
@@ -855,15 +1381,19 @@ export class TurbineClient {
             autoToOneJoinMaxRows: config.autoToOneJoinMaxRows,
             autoRoundTripMs: config.autoRoundTripMs,
             jsonEncoding: config.jsonEncoding,
-            globalFilters: config.globalFilters,
-            preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
+            globalFilters,
+            preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? (!config.pool && !pooler)),
             // Forwarded so a per-query `forceCustomPlan` can refuse the combination
             // this client's own connections would silently defeat, see the
             // `planCacheMode` note on QueryInterfaceOptions.
             planCacheMode,
             sqlCache: config.sqlCache ?? true,
             sqlCacheSize: config.sqlCacheSize,
+            streamIdleTimeoutMs,
+            _sqlCommenter: sqlComment,
             dialect: config.dialect,
+            diagnostics,
+            logger,
             // Non-SQL backends (PowDB) inject a factory that builds their own query
             // interface (PowqlInterface) instead of the SQL QueryInterface. SQL engines
             // never set this, so `table()` keeps constructing `new QueryInterface`.
@@ -883,7 +1413,7 @@ export class TurbineClient {
                     }
                     catch (e) {
                         if (this.logging)
-                            console.error('[turbine] Query listener error:', e);
+                            logTo(this.logger, 'error', 'Query listener error:', { code: 'query-listener-error', error: e });
                     }
                 }
             },
@@ -906,11 +1436,24 @@ export class TurbineClient {
         if (config.pool) {
             // External pool, use directly. Turbine doesn't manage its lifecycle.
             this.pool = config.pool;
+            // Turbine registers no parsers for a pool it did not open, so its own
+            // queries on this one carry them instead.
+            this.queryPool = this.typedPool(config.pool);
             this.ownsPool = false;
             if (this.logging) {
-                console.log(`[turbine] Using external pool, ${Object.keys(schema.tables).length} tables`);
+                const tables = Object.keys(schema.tables).length;
+                logTo(this.logger, 'debug', `Using external pool, ${tables} tables`, { code: 'external-pool', tables });
             }
         }
+        else if (!hasDatabaseTarget(config)) {
+            // Nothing names a database: no pool, connection string, host settings,
+            // DATABASE_URL or PG* variable. The first query fails with the fix,
+            // which beats connecting to a guessed localhost. Failing here instead
+            // would break every build step that imports the client without a database.
+            this.pool = unconfiguredPool(config.connectionString === '');
+            this.queryPool = this.pool;
+            this.ownsPool = true;
+        }
         else {
             const poolConfig = {
                 max: config.poolSize ?? config.max ?? 10,
@@ -937,10 +1480,12 @@ export class TurbineClient {
                 poolConfig.connectionString = process.env.DATABASE_URL;
             }
             else {
-                poolConfig.host = config.host ?? 'localhost';
-                poolConfig.port = config.port ?? 5432;
-                poolConfig.database = config.database ?? 'postgres';
-                poolConfig.user = config.user ?? 'postgres';
+                // A default filled in here would override the PG* variable pg reads
+                // for the same field, so a field the environment sets is left to pg.
+                poolConfig.host = config.host ?? (pgEnv('PGHOST') ? undefined : 'localhost');
+                poolConfig.port = config.port ?? (pgEnv('PGPORT') ? undefined : 5432);
+                poolConfig.database = config.database ?? (pgEnv('PGDATABASE') ? undefined : 'postgres');
+                poolConfig.user = config.user ?? (pgEnv('PGUSER') ? undefined : 'postgres');
                 poolConfig.password = config.password;
             }
             if (config.ssl !== undefined) {
@@ -949,19 +1494,25 @@ export class TurbineClient {
             // Held as a `pg.Pool` for the length of this block: `PgCompatPool.on` is
             // optional (HTTP drivers have no pool events), and here we know we own a
             // real pg pool that has one. Same shape as the replica loop below.
-            const ownPool = new pg.Pool(TurbineClient.withPlanCacheMode(poolConfig, this.planCacheMode));
-            ownPool.on('error', (err) => {
-                console.error('[turbine] Unexpected pool error:', err.message);
-            });
-            absorbCheckedOutErrors(ownPool);
+            const ownPool = new pg.Pool(TurbineClient.ownedPoolConfig(poolConfig, planCacheMode, statementTimeoutMs, maxLifetimeSeconds));
+            this.watchOwnedPool(ownPool, { pool: 'primary' });
             // After a freeze (a serverless function between invocations), wait one
             // loop turn before reusing a long-idle connection, so the pool has read
             // any close the server sent meanwhile. See connection-guard.ts.
             settleLongIdleCheckouts(ownPool);
+            // An exhausted pool rejects a checkout with an untyped pg-pool error;
+            // make it a ConnectionError on every path, `pool.query` included.
+            typeCheckoutTimeouts(ownPool);
             this.pool = ownPool;
+            this.queryPool = ownPool;
             this.ownsPool = true;
             if (this.logging) {
-                console.log(`[turbine] Pool created, max ${poolConfig.max} connections, ${Object.keys(schema.tables).length} tables`);
+                const tables = Object.keys(schema.tables).length;
+                logTo(this.logger, 'debug', `Pool created, max ${poolConfig.max} connections, ${tables} tables`, {
+                    code: 'pool-created',
+                    max: poolConfig.max,
+                    tables,
+                });
             }
         }
         // Build read-replica pools (if any). String entries become owned pg.Pools
@@ -971,23 +1522,23 @@ export class TurbineClient {
         this.ownedReplicaPools = [];
         for (const replica of config.replicas ?? []) {
             if (typeof replica === 'string') {
-                const replicaPool = new pg.Pool(TurbineClient.withPlanCacheMode({
+                const replicaPool = new pg.Pool(TurbineClient.ownedPoolConfig({
                     connectionString: replica,
                     max: config.poolSize ?? config.max ?? 10,
                     idleTimeoutMillis: config.idleTimeoutMs ?? config.idleTimeoutMillis ?? 30_000,
                     connectionTimeoutMillis: config.connectionTimeoutMs ?? config.connectionTimeoutMillis ?? 5_000,
                     ...(config.ssl !== undefined ? { ssl: config.ssl } : {}),
-                }, this.planCacheMode));
-                replicaPool.on('error', (err) => {
-                    console.error('[turbine] Unexpected replica pool error:', err.message);
-                });
-                absorbCheckedOutErrors(replicaPool);
+                }, planCacheMode, statementTimeoutMs, maxLifetimeSeconds));
+                this.watchOwnedPool(replicaPool, { pool: 'replica', replica: this.replicaPools.length });
                 settleLongIdleCheckouts(replicaPool);
-                this.replicaPools.push(replicaPool);
+                typeCheckoutTimeouts(replicaPool);
+                // Next to a supplied primary no parsers were registered, so this
+                // replica's reads carry them like the primary's do.
+                this.replicaPools.push(this.ownsPool ? replicaPool : this.typedPool(replicaPool));
                 this.ownedReplicaPools.push(replicaPool);
             }
             else {
-                this.replicaPools.push(replica);
+                this.replicaPools.push(this.typedPool(replica));
             }
         }
         // `planCacheMode` reaches a pool only where Turbine opens the connections.
@@ -998,26 +1549,34 @@ export class TurbineClient {
         // Deliberate no-op rather than a throw: the option is a performance knob,
         // and an app that moves from an owned pool to a serverless driver should
         // not stop booting over it. Same ownership rule as the type parsers, which
-        // also skip external pools silently.
-        if (this.planCacheMode !== undefined && !this.ownsPool && process.env.NODE_ENV !== 'production') {
+        // also skip external pools silently. Always on, like every construction
+        // warning: the option is just as ignored in production.
+        if (this.planCacheMode !== undefined && !this.ownsPool) {
             if (shouldWarnOnce(WARN_NS.planCacheModeIgnored, this.planCacheMode)) {
                 const replicaNote = this.ownedReplicaPools.length > 0
                     ? ` It IS applied to the ${this.ownedReplicaPools.length} Turbine-owned read replica pool(s) on this ` +
                         'client, so reads and writes would run under different plan-cache policies until the primary is set too.'
                     : '';
-                console.warn(`[turbine] planCacheMode: '${this.planCacheMode}' was not applied to the primary: this client was given an ` +
+                logTo(this.logger, 'warn', `planCacheMode: '${this.planCacheMode}' was not applied to the primary: this client was given an ` +
                     'external `pool`, whose connection lifecycle the caller owns, so Turbine never opens its connections. Set ' +
                     `\`plan_cache_mode\` in the driver's own connection setup (or run \`SET plan_cache_mode = ${this.planCacheMode}\` ` +
-                    `on checkout) instead.${replicaNote}`);
+                    `on checkout) instead.${replicaNote}`, { code: 'plan-cache-mode-ignored', option: 'planCacheMode', ownedReplicas: this.ownedReplicaPools.length });
             }
         }
+        this.warnExternalPoolOptions(statementTimeoutMs, maxLifetimeSeconds);
         this.replicaTableCaches = this.replicaPools.map(() => new Map());
         if (this.logging && this.replicaPools.length > 0) {
-            console.log(`[turbine] ${this.replicaPools.length} read replica(s) configured (${this.ownedReplicaPools.length} owned)`);
+            const replicas = this.replicaPools.length;
+            const owned = this.ownedReplicaPools.length;
+            logTo(this.logger, 'debug', `${replicas} read replica(s) configured (${owned} owned)`, {
+                code: 'replicas-configured',
+                replicas,
+                owned,
+            });
         }
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
-            const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+            const camelName = tableAccessorName(tableName);
             if (!(camelName in this)) {
                 Object.defineProperty(this, camelName, {
                     get: () => this.table(tableName),
@@ -1079,8 +1638,10 @@ export class TurbineClient {
         return matched;
     }
     /**
-     * Pin `plan_cache_mode` on every connection an OWNED pool opens, by putting
-     * it in the pool's **connection parameters** rather than issuing a `SET`.
+     * The pg pool config for a pool Turbine opens: the `maxLifetimeSeconds`
+     * recycling default, plus `plan_cache_mode` and `statement_timeout` pinned
+     * on every connection through the pool's **connection parameters** rather
+     * than a `SET`.
      *
      * PostgreSQL's `options` startup parameter (`-c plan_cache_mode=...`) is
      * applied by the backend as it starts the session, so the setting is in force
@@ -1114,23 +1675,157 @@ export class TurbineClient {
      * should set the GUC on the server or role instead
      * (`ALTER ROLE ... SET plan_cache_mode = ...`).
      */
-    static withPlanCacheMode(poolConfig, mode) {
-        if (mode === undefined)
-            return poolConfig;
-        // `mode` is a member of PLAN_CACHE_MODES, never caller text (see
-        // resolvePlanCacheMode), which is what makes this literal safe: a GUC value
-        // cannot be a bind parameter.
-        const setting = `-c plan_cache_mode=${mode}`;
-        const merged = poolConfig.connectionString
-            ? mergeConnectionStringOptions(poolConfig.connectionString, setting)
-            : null;
-        if (merged)
-            return { ...poolConfig, connectionString: merged };
-        // pg reads `config.options` when truthy and `process.env.PGOPTIONS`
-        // otherwise, so an unmerged setting would replace the caller's PGOPTIONS
-        // rather than add to it.
-        const existing = poolConfig.options || (typeof process !== 'undefined' ? process.env?.PGOPTIONS : undefined);
-        return { ...poolConfig, options: existing ? `${existing} ${setting}` : setting };
+    static ownedPoolConfig(poolConfig, planCacheMode, statementTimeoutMs, maxLifetimeSeconds) {
+        let config = {
+            ...poolConfig,
+            maxLifetimeSeconds: maxLifetimeSeconds ?? DEFAULT_MAX_LIFETIME_SECONDS,
+        };
+        // `planCacheMode` is a member of PLAN_CACHE_MODES and `statementTimeoutMs`
+        // a narrowed integer, never caller text, which is what makes these
+        // literals safe: a GUC value cannot be a bind parameter.
+        if (planCacheMode !== undefined)
+            config = withStartupSetting(config, `-c plan_cache_mode=${planCacheMode}`);
+        const timeout = statementTimeoutMs === undefined ? null : statementTimeoutSetting(statementTimeoutMs);
+        if (timeout !== null)
+            config = withStartupSetting(config, timeout);
+        return config;
+    }
+    /**
+     * Validate `statementTimeoutMs`: a non-negative integer (E003), on
+     * PostgreSQL only (E017), since it is applied as a PostgreSQL connection
+     * parameter.
+     */
+    static resolveStatementTimeout(value, dialect) {
+        const ms = resolveNonNegativeInteger(value, 'statementTimeoutMs', 'milliseconds');
+        if (ms !== undefined && !dialect.capabilities.connectionParameters) {
+            throw new UnsupportedFeatureError(`The statementTimeoutMs option (statement_timeout = ${ms})`, dialect.name, '`statement_timeout` is applied as a PostgreSQL connection parameter. Remove the option on this engine, ' +
+                'and bound slow statements with the per-query `timeout` instead.');
+        }
+        return ms;
+    }
+    /**
+     * The first connection target this client opens that names a connection
+     * pooler (see `detectPooler`), as `host:port`, or `undefined`. Covers the
+     * connection string, the DATABASE_URL fallback, host/port settings, and
+     * string replicas, each read the way node-postgres reads it: a host or port
+     * the target leaves unset is `PGHOST` / `PGPORT`.
+     */
+    static poolerEndpoint(config) {
+        const explicit = config.connectionString != null ||
+            config.host != null ||
+            config.port != null ||
+            config.database != null ||
+            config.user != null ||
+            config.password != null;
+        const targets = [];
+        if (config.connectionString)
+            targets.push(parseConnectionTarget(config.connectionString));
+        else if (!explicit && process.env.DATABASE_URL)
+            targets.push(parseConnectionTarget(process.env.DATABASE_URL));
+        else {
+            targets.push({
+                host: config.host ? config.host.toLowerCase() : null,
+                port: typeof config.port === 'number' ? config.port : null,
+            });
+        }
+        for (const replica of config.replicas ?? []) {
+            if (typeof replica === 'string' && replica)
+                targets.push(parseConnectionTarget(replica));
+        }
+        const environment = { host: pgEnv('PGHOST'), port: pgEnv('PGPORT') };
+        for (const target of targets) {
+            const found = detectPoolerTarget(fillTargetFromEnvironment(target, environment));
+            if (found.pooled)
+                return `${found.host ?? 'localhost'}:${found.port ?? 5432}`;
+        }
+        return undefined;
+    }
+    /** Always on: named statements behind a transaction pooler fail in production first. */
+    static warnPreparedOnPooler(endpoint, logger) {
+        if (!shouldWarnOnce(WARN_NS.preparedStatementsOnPooler, endpoint))
+            return;
+        logTo(logger, 'warn', `preparedStatements: true on ${endpoint}, which looks like a connection pooler. In transaction ` +
+            'mode a pooler runs each transaction on any server connection, so a statement named on one fails on ' +
+            'the next ("prepared statement ... does not exist" or "already exists") unless the pooler tracks ' +
+            'prepared statements: PgBouncer 1.21+ with max_prepared_statements above 0. If yours does not, leave ' +
+            'preparedStatements unset; Turbine then sends unnamed statements to a pooler.', { code: 'prepared-statements-on-pooler', endpoint });
+    }
+    /**
+     * `pool` as Turbine's own statements should reach it: with Turbine's int8
+     * and temporal parsers on every query, for a PostgreSQL pool built on
+     * node-postgres. Any other pool is returned unchanged.
+     */
+    typedPool(pool) {
+        if (this.dialect.capabilities.connectionDriver !== 'pg-compatible')
+            return pool;
+        return typedQueryPool(pool, this.queryOptions.utcTimestamps !== false) ?? pool;
+    }
+    /**
+     * Listen to a pool this client opened: its idle-connection errors become
+     * `poolError` events, a checked-out connection's loss a `connectionLost`
+     * event, and its checkouts are tracked for `disconnect({ timeoutMs })`.
+     * Also the connection guards every owned pool gets (connection-guard.ts):
+     * no unheard `'error'`, a settle after a freeze, typed checkout timeouts.
+     */
+    watchOwnedPool(pool, origin) {
+        pool.on('error', (err) => this.emitPoolEvent('poolError', { error: err, ...origin }));
+        absorbCheckedOutErrors(pool);
+        this.checkoutWatches.push(watchCheckouts(pool, (err) => this.emitPoolEvent('connectionLost', { error: err, ...origin })));
+    }
+    /**
+     * Hand a pool event to its listeners. A `poolError` with no listener is
+     * logged at `error`, always; a listener that throws is ignored, like a query
+     * listener.
+     */
+    emitPoolEvent(kind, event) {
+        const listeners = this.poolListeners[kind];
+        if (listeners.size === 0) {
+            if (kind === 'poolError') {
+                logTo(this.logger, 'error', `Unexpected ${event.pool} pool error: ${event.error.message}`, {
+                    code: 'pool-error',
+                    pool: event.pool,
+                    ...(event.replica !== undefined ? { replica: event.replica } : {}),
+                    error: event.error,
+                });
+            }
+            return;
+        }
+        for (const listener of listeners) {
+            try {
+                listener(event);
+            }
+            catch (e) {
+                if (this.logging) {
+                    logTo(this.logger, 'error', `${kind} listener error:`, {
+                        code: 'pool-listener-error',
+                        listener: kind,
+                        error: e,
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * `statementTimeoutMs` and an explicit `maxLifetimeSeconds` reach only the
+     * pools Turbine opens. On an external primary they do nothing, which a
+     * warning says once, naming where the setting belongs instead. Always on: an
+     * ignored timeout means no timeout in production.
+     */
+    warnExternalPoolOptions(statementTimeoutMs, maxLifetimeSeconds) {
+        if (this.ownsPool)
+            return;
+        const ownedReplicas = this.ownedReplicaPools.length;
+        if (statementTimeoutMs !== undefined && shouldWarnOnce(WARN_NS.connectionOptionIgnored, 'statementTimeoutMs')) {
+            logTo(this.logger, 'warn', `statementTimeoutMs: ${statementTimeoutMs} was not applied to the primary: this client was given an ` +
+                "external `pool`, whose connections Turbine never opens. Set `statement_timeout` in the driver's own " +
+                "connection setup, or on the role (`ALTER ROLE app SET statement_timeout = '30s'`)." +
+                (ownedReplicas > 0 ? ' It IS applied to the Turbine-owned read replica pools.' : ''), { code: 'connection-option-ignored', option: 'statementTimeoutMs', ownedReplicas });
+        }
+        if (maxLifetimeSeconds !== undefined && shouldWarnOnce(WARN_NS.connectionOptionIgnored, 'maxLifetimeSeconds')) {
+            logTo(this.logger, 'warn', `maxLifetimeSeconds: ${maxLifetimeSeconds} was not applied to the primary: this client was given ` +
+                "an external `pool`, whose connection lifecycle the caller owns. Set it on that pool's own options." +
+                (ownedReplicas > 0 ? ' It IS applied to the Turbine-owned read replica pools.' : ''), { code: 'connection-option-ignored', option: 'maxLifetimeSeconds', ownedReplicas });
+        }
     }
     /**
      * Refuse a `utcTimestamps` value that contradicts the one an earlier client
@@ -1235,14 +1930,18 @@ export class TurbineClient {
         // OUTERMOST, so leaving it out silently defeats all three above.
         this.errorScopedTableCache.clear();
     }
-    // -------------------------------------------------------------------------
-    // Event emitter, subscribe to query lifecycle events
-    // -------------------------------------------------------------------------
-    $on(_event, listener) {
-        this.queryListeners.add(listener);
+    $on(event, listener) {
+        this.listenersFor(event, '$on').add(listener);
+    }
+    $off(event, listener) {
+        this.listenersFor(event, '$off').delete(listener);
     }
-    $off(_event, listener) {
-        this.queryListeners.delete(listener);
+    listenersFor(event, api) {
+        if (event === 'query')
+            return this.queryListeners;
+        if (event === 'poolError' || event === 'connectionLost')
+            return this.poolListeners[event];
+        throw new ValidationError(`${api}: unknown event ${JSON.stringify(event)}. Expected 'query', 'poolError' or 'connectionLost'.`);
     }
     // -------------------------------------------------------------------------
     // Observability, automatic metrics collection
@@ -1332,21 +2031,23 @@ export class TurbineClient {
      */
     createErrorModeAccessor(target) {
         const mode = this.errorMessageMode;
+        // Keyed by name AND the function found under it, so a method replaced
+        // after first use (a spy, a mock, an APM patch) is the one that runs.
         const wrapped = new Map();
         return new Proxy(target, {
             get(t, prop, receiver) {
                 const value = Reflect.get(t, prop, receiver);
                 if (typeof value !== 'function' || typeof prop !== 'string')
                     return value;
-                let fn = wrapped.get(prop);
-                if (!fn) {
-                    fn = (...args) => {
-                        const call = () => value.apply(t, args);
-                        return errorMessageModesDiverged() ? runWithErrorMessageMode(mode, call) : call();
-                    };
-                    wrapped.set(prop, fn);
-                }
-                return fn;
+                const hit = wrapped.get(prop);
+                if (hit !== undefined && hit.fn === value)
+                    return hit.wrapper;
+                const wrapper = (...args) => {
+                    const call = () => value.apply(t, args);
+                    return errorMessageModesDiverged() ? runWithErrorMessageMode(mode, call) : call();
+                };
+                wrapped.set(prop, { fn: value, wrapper });
+                return wrapper;
             },
         });
     }
@@ -1369,7 +2070,7 @@ export class TurbineClient {
     primaryTableQI(name) {
         let qi = this.tableCache.get(name);
         if (!qi) {
-            qi = this.buildTableQI(this.pool, name);
+            qi = this.buildTableQI(this.queryPool, name);
             this.tableCache.set(name, qi);
         }
         return qi;
@@ -1395,7 +2096,7 @@ export class TurbineClient {
     /** Construct a QueryInterface bound to `pool` (honoring any injected factory). */
     buildTableQI(pool, name) {
         return this.queryOptions?.queryInterfaceFactory
-            ? this.queryOptions.queryInterfaceFactory(pool, name, this.schema, this.middlewares, this.queryOptions)
+            ? asQueryInterface(this.queryOptions.queryInterfaceFactory(pool, name, this.schema, this.middlewares, this.queryOptions))
             : new QueryInterface(pool, name, this.schema, this.middlewares, this.queryOptions);
     }
     /**
@@ -1406,20 +2107,30 @@ export class TurbineClient {
     createRoutingAccessor(name) {
         const primaryQI = this.primaryTableQI(name);
         const client = this;
+        // One routing function per operation, so the accessor above can tell a
+        // replaced method from this one by identity.
+        const routed = new Map();
         return new Proxy(primaryQI, {
             get(target, prop, receiver) {
-                if (typeof prop === 'string' && READ_OPERATIONS.has(prop)) {
+                // A read replaced on the accessor (a spy, a mock) is an own property of
+                // the primary instance, and runs as installed rather than routed past.
+                if (typeof prop !== 'string' || !READ_OPERATIONS.has(prop) || Object.hasOwn(target, prop)) {
+                    return Reflect.get(target, prop, receiver);
+                }
+                let route = routed.get(prop);
+                if (route === undefined) {
                     // Pick the replica at CALL time so round-robin advances per operation.
-                    return (...args) => {
+                    route = (...args) => {
                         const replicaQI = client.nextReplicaTableQI(name);
                         const method = replicaQI[prop];
                         if (typeof method !== 'function') {
-                            return Reflect.get(target, prop, receiver);
+                            return Reflect.get(target, prop, receiver).apply(target, args);
                         }
                         return method.apply(replicaQI, args);
                     };
+                    routed.set(prop, route);
                 }
-                return Reflect.get(target, prop, receiver);
+                return route;
             },
         });
     }
@@ -1456,27 +2167,13 @@ export class TurbineClient {
         }
         return this.primaryView;
     }
-    // -------------------------------------------------------------------------
-    // Pipeline, batch multiple queries into one round-trip
-    // -------------------------------------------------------------------------
-    /**
-     * Execute multiple queries in a single database round-trip.
-     *
-     * Two call styles:
-     *   - `db.pipeline(q1, q2, q3)`, rest params (backward-compatible)
-     *   - `db.pipeline([q1, q2, q3], { transactional: false })`, array + options
-     *
-     * On pg.Pool-backed connections with TCP, this uses the real Postgres
-     * extended-query pipeline protocol (one TCP flush, one round-trip).
-     * On HTTP-based drivers it falls back to sequential execution.
-     */
     async pipeline(...args) {
         let queries;
         let options;
-        // Detect which overload was used
-        if (args.length > 0 &&
-            Array.isArray(args[0]) &&
-            args[0].every((item) => item && typeof item === 'object' && 'sql' in item)) {
+        // Detect which overload was used. A deferred query is never an array, so
+        // an array first argument is the array form whatever it contains; its
+        // items are checked below like the rest form's.
+        if (args.length > 0 && Array.isArray(args[0])) {
             // Array form: pipeline([q1, q2], opts?)
             queries = args[0];
             options = args[1];
@@ -1485,8 +2182,18 @@ export class TurbineClient {
             // Rest-param form: pipeline(q1, q2, q3)
             queries = args;
         }
+        assertDeferredQueries(queries, 'pipeline', 'pipeline');
+        // A locking read outside a transaction would release its locks before
+        // the caller saw the rows; a transactional pipeline keeps them for the batch.
+        if (options?.transactional === false)
+            assertNoLockInAutocommitPipeline(queries);
         if (this.logging) {
-            console.log(`[turbine] Pipeline: ${queries.length} queries, ${queries.map((q) => q.tag).join(', ')}`);
+            const tags = queries.map((q) => q.tag);
+            logTo(this.logger, 'debug', `Pipeline: ${queries.length} queries, ${tags.join(', ')}`, {
+                code: 'pipeline',
+                queries: queries.length,
+                tags,
+            });
         }
         // Scoped like every other entry point. A pipeline builds NotFoundErrors (a
         // `buildFindUniqueOrThrow` slot) and wraps driver errors into
@@ -1495,10 +2202,27 @@ export class TurbineClient {
         // where VALUES as soon as any verbose client existed in the process. The
         // scope is established around the await, so every continuation of the batch
         // resolves this client's mode.
+        // Each statement carries the `sqlComment` its query interface would have
+        // given it, computed here in the caller's async context.
+        const comments = this.statementComments(queries);
+        const sent = comments ? queries.map((q, i) => commentDeferred(q, comments[i])) : queries;
         const sink = this.queryListeners.size > 0 ? this.queryOptions._onQuery : undefined;
         if (!sink)
-            return this.withErrorMode(() => executePipeline(this.pool, queries, options));
-        return this.withErrorMode(() => this.reportedPipeline(sink, queries, options));
+            return this.withErrorMode(() => executePipeline(this.queryPool, sent, options));
+        return this.withErrorMode(() => this.reportedPipeline(sink, queries, options, sent, comments));
+    }
+    /**
+     * The `sqlComment` of each deferred query, named by its own model and action
+     * (a pipeline can mix tables), or `undefined` when this client adds none.
+     */
+    statementComments(queries) {
+        const commenter = this.sqlCommenter;
+        if (commenter === undefined)
+            return undefined;
+        return queries.map((q) => {
+            const { model, action } = deferredIdentity(q.tag);
+            return commenter.commentFor(model, action)?.comment;
+        });
     }
     /**
      * {@link pipeline} with one `$on('query')` event per statement. Only taken
@@ -1509,9 +2233,9 @@ export class TurbineClient {
      * time is split evenly across them and each event carries
      * `batch: 'pipeline'`.
      */
-    async reportedPipeline(sink, queries, options) {
+    async reportedPipeline(sink, queries, options, sent, comments) {
         const rowCounts = new Array(queries.length).fill(undefined);
-        const observed = queries.map((q, i) => ({
+        const observed = sent.map((q, i) => ({
             ...q,
             transform: (raw) => {
                 rowCounts[i] = resultRowCount(raw);
@@ -1521,7 +2245,7 @@ export class TurbineClient {
         const start = performance.now();
         let failure;
         try {
-            return await executePipeline(this.pool, observed, options);
+            return await executePipeline(this.queryPool, observed, options);
         }
         catch (err) {
             failure = err;
@@ -1547,6 +2271,7 @@ export class TurbineClient {
                         ...deferredIdentity(q.tag),
                         rows: rowCounts[i] ?? 0,
                         batch: 'pipeline',
+                        ...(comments?.[i] === undefined ? {} : { comment: comments[i] }),
                         ...(failed ? { error: failure instanceof Error ? failure : new Error(String(failure)) } : {}),
                     });
                 }
@@ -1559,13 +2284,17 @@ export class TurbineClient {
      * drivers (Neon HTTP, Vercel Postgres, etc.) and mock pools.
      */
     async pipelineSupported() {
-        return pipelineSupported(this.pool);
+        return pipelineSupported(this.queryPool);
     }
     // -------------------------------------------------------------------------
     // Raw SQL, tagged template literal escape hatch
     // -------------------------------------------------------------------------
     /**
      * Execute a raw SQL query with parameter interpolation via tagged templates.
+     * Every `${value}` is sent as a bound parameter. Only a real tagged-template
+     * call is accepted: an array passed in its place throws `ValidationError`
+     * (E003), since its text would reach the SQL unescaped. For statement text
+     * built at runtime, see {@link rawUnsafe}.
      *
      * @example
      * ```ts
@@ -1577,17 +2306,40 @@ export class TurbineClient {
      * ```
      */
     async raw(strings, ...values) {
-        let sql = '';
-        strings.forEach((str, i) => {
-            sql += str;
-            if (i < values.length) {
-                sql += this.dialect.paramPlaceholder(i + 1);
-            }
-        });
+        const { sql, params } = buildTypedSql(strings, values, this.dialect, 'raw');
+        return this.runRaw(sql, params, 'raw');
+    }
+    /**
+     * Execute SQL text built at runtime: DDL read from a file, a statement in
+     * another engine's own language (PowQL), a migration step. Values go in
+     * `values` and are referenced from the text with the engine's placeholders
+     * (`$1`, `$2`, ... on PostgreSQL), so they are still bound.
+     *
+     * NOTHING IN `text` IS ESCAPED. It is the one raw entry point where
+     * concatenating input into the statement is possible, which is why it is
+     * separate from {@link raw} and named for it: never build `text` from
+     * request data. Prefer {@link raw} or {@link sql} wherever the statement is
+     * known when the code is written.
+     *
+     * @example
+     * ```ts
+     * for (const statement of ddlStatements) await db.rawUnsafe(statement);
+     * await db.rawUnsafe('SELECT * FROM users WHERE id = $1', userId);
+     * ```
+     */
+    async rawUnsafe(text, ...values) {
+        assertSqlText(text, 'rawUnsafe');
+        return this.runRaw(text, values, 'rawUnsafe');
+    }
+    async runRaw(sql, values, action) {
+        const params = this.rawParams(values, action);
         if (this.logging) {
-            console.log(`[turbine] Raw SQL: ${sql.trim().substring(0, 120)}...`);
+            logTo(this.logger, 'debug', `Raw SQL: ${sql.trim().substring(0, 120)}...`, {
+                code: 'raw-sql',
+                operation: action,
+            });
         }
-        const result = await runReportedStatement(this.queryOptions._onQuery, rawIdentity('raw'), sql, values, () => this.pool.query(sql, values), (err) => this.withErrorMode(() => wrapPgError(err)));
+        const result = await runReportedStatement(this.queryOptions._onQuery, rawIdentity(action), sql, params, () => this.queryPool.query(sql, params), (err) => this.withErrorMode(() => wrapPgError(err)));
         return result.rows;
     }
     /**
@@ -1600,9 +2352,20 @@ export class TurbineClient {
      * the pool. Errors are translated by `wrapPgError`, like {@link raw}.
      */
     async rawQuery(text, params = [], action = 'rawQuery') {
-        const result = await runReportedStatement(this.queryOptions._onQuery, rawIdentity(action), text, params, () => this.pool.query(text, params), (err) => this.withErrorMode(() => wrapPgError(err)));
+        const bound = this.rawParams(params, action);
+        const result = await runReportedStatement(this.queryOptions._onQuery, rawIdentity(action), text, bound, () => this.queryPool.query(text, bound), (err) => this.withErrorMode(() => wrapPgError(err)));
         return { rows: result.rows, rowCount: result.rowCount };
     }
+    /**
+     * Bound Dates as UTC text, on a PostgreSQL client reading zone-less temporal
+     * types as UTC (see {@link utcDateParams}). Typed builder writes convert per
+     * column instead and never come through here.
+     */
+    rawParams(params, api) {
+        return this.dialect.capabilities.utcTimestampRewrite && this.queryOptions.utcTimestamps !== false
+            ? utcDateParams(params, api)
+            : params;
+    }
     /**
      * Run `fn` with `tag` attached to every `$on('query')` event it causes, so a
      * listener can attribute queries to the feature or code path that issued
@@ -1656,14 +2419,15 @@ export class TurbineClient {
      * ```
      */
     sql(strings, ...values) {
-        const { sql, params } = buildTypedSql(strings, values, this.dialect);
+        const { sql, params: bound } = buildTypedSql(strings, values, this.dialect);
+        const params = this.rawParams(bound, 'sql');
         // The scope has to be handed to the BUILDER, not wrapped around this call.
         // `TypedSqlQuery` is lazy (it runs on `await` / `.one()` / `.scalar()`), so
         // a scope opened here would close before any row was fetched. The
         // `withErrorMode` docstring already claimed to cover the typed-SQL builder
         // and did not, which left two raw-SQL entry points disagreeing about the
         // same statement, since the adjacent `raw` tag WAS scoped.
-        return new TypedSqlQuery(this.pool, sql, params, this.logging, (fn) => this.withErrorMode(fn), this.queryOptions._onQuery);
+        return new TypedSqlQuery(this.queryPool, sql, params, this.logging, (fn) => this.withErrorMode(fn), this.queryOptions._onQuery, this.logger);
     }
     // -------------------------------------------------------------------------
     // Transaction support (raw, legacy)
@@ -1673,10 +2437,16 @@ export class TurbineClient {
      * connection. For the typed API, use `$transaction()` instead.
      *
      * The client is typed as {@link PgCompatPoolClient}, the driver-neutral
-     * contract: `query(text, values)` plus `release()`, which is all any
-     * supported driver guarantees. For the pg-only surface (cursors, COPY
-     * streams, the `QueryConfig` object form), import `PoolClient` from the pg
-     * package and cast: `client as unknown as PoolClient`.
+     * contract: `query(text, values)`, which is all any supported driver
+     * guarantees. For the pg-only surface (cursors, COPY streams, the
+     * `QueryConfig` object form), import `PoolClient` from the pg package and
+     * cast: `client as unknown as PoolClient`.
+     *
+     * Like `$transaction`'s `tx`, the client is closed when the transaction
+     * settles: a query sent through it afterwards throws `ValidationError`
+     * (E003). The callback must not `release()` it, and must await every query
+     * it starts: one still running when the callback returns rolls the
+     * transaction back with E003.
      *
      * @example
      * ```ts
@@ -1694,28 +2464,32 @@ export class TurbineClient {
         // driver with one shared engine handle (PowDB embedded) would roll back a
         // DIFFERENT caller's open transaction.
         const { client, checkout } = await openCheckout(this.pool, (c) => runTxControl(c, this.dialect.beginStatement()));
+        const state = new TransactionState(client, this.dialect, { api: 'transaction' });
+        const guarded = closableRawClient(client, state);
         try {
             // Engine seam: single-writer engines scope their transaction re-entrancy
             // marker to the callback's async subtree (see
             // PgCompatPoolClient.wrapTransactionCallback). Absent everywhere else.
             const wrap = client.wrapTransactionCallback;
             // `.call` erases the generic, so the callback's Promise<T> is re-asserted.
-            const result = wrap ? (await wrap.call(client, () => fn(client))) : await fn(client);
-            await runTxControl(client, this.dialect.commitStatement());
+            const result = wrap ? (await wrap.call(client, () => fn(guarded))) : await fn(guarded);
+            const unawaited = state.busy;
+            state.end('has ended');
+            if (unawaited)
+                throw unawaitedWorkError('transaction');
+            // A COMMIT answered with ROLLBACK (a statement failed and the callback
+            // caught it) rejects, with the first failed statement as the cause.
+            await commitTransaction(client, this.dialect.commitStatement(), state.firstFailure, 'transaction');
+            state.end('committed');
+            checkout.release();
             return result;
         }
         catch (err) {
-            try {
-                await client.query(this.dialect.rollbackStatement());
-            }
-            catch {
-                // Best-effort rollback, the connection may have died mid-query.
-            }
+            state.end('was rolled back');
+            const clean = await rollbackOnServer(client, state, this.dialect);
+            checkout.release(clean ? undefined : new Error('[turbine] transaction connection discarded: rollback not confirmed'));
             throw explainConnectionLoss(err, checkout.lostWith);
         }
-        finally {
-            checkout.release();
-        }
     }
     async $transaction(fnOrQueries, options) {
         // Scope the WHOLE call, so the transaction-scoped QueryInterfaces built
@@ -1725,145 +2499,183 @@ export class TurbineClient {
     }
     async runTransaction(fnOrQueries, options) {
         // Batch overload: an array of DeferredQuery objects runs atomically inside
-        // one BEGIN…COMMIT, reusing the raw transaction machinery below.
+        // one BEGIN…COMMIT, through the same lifecycle (and options) as a callback.
         if (Array.isArray(fnOrQueries)) {
-            return this.transactionBatch(fnOrQueries);
+            assertDeferredQueries(fnOrQueries, '$transaction([...])', 'transaction');
+            if (fnOrQueries.length === 0) {
+                this.resolveTransactionOptions(options);
+                return [];
+            }
+            return this.runInTransaction(options, (client, state) => this.runBatch(client, state, fnOrQueries));
+        }
+        if (typeof fnOrQueries !== 'function') {
+            throw new ValidationError('$transaction expects a callback, `async (tx) => { ... }`, or an array of deferred queries built with ' +
+                `\`build*()\`, but received ${fnOrQueries === null ? 'null' : typeof fnOrQueries}.`);
         }
         const fn = fnOrQueries;
-        // Resolve the isolation level BEFORE taking a pool slot: a bad argument is
-        // the caller's bug and should not cost a connection to discover.
+        // Pass the parent pool so its read-only guard + PowDB capabilities flow
+        // into the transaction-scoped proxy pool (see TransactionClient.createTxPool).
+        const sourcePool = this.pool;
+        return this.runInTransaction(options, (client, state) => fn(new TransactionClient(client, this.schema, this.middlewares, this.queryOptions, sourcePool, state)));
+    }
+    /**
+     * Validate every transaction option and build the statements they need,
+     * BEFORE a pool slot is taken: a bad argument is the caller's bug and should
+     * not cost a connection to discover.
+     */
+    resolveTransactionOptions(options) {
         const isolationSql = resolveIsolationLevel(options?.isolationLevel);
-        // BEGIN with optional isolation level, the dialect owns the keyword and
-        // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`). It
-        // runs inside openCheckout, which sends it once more on a fresh connection
-        // when the first one turns out to be dead, and which releases the
-        // connection itself when BEGIN fails for good. So everything below runs in
-        // a transaction that began.
-        const { client, checkout } = await openCheckout(this.pool, (c) => runTxControl(c, this.dialect.beginStatement(isolationSql)));
+        const begin = beginStatementFor(this.dialect, isolationSql, resolveReadOnly(options?.readOnly));
+        const sessionConfig = this.resolveSessionContext(options?.sessionContext, options?.allowBuiltinSettings);
         const timeout = options?.timeout;
-        /**
-         * Track whether the connection has already been released so the finally
-         * block doesn't double-release. When a timeout fires we destroy the
-         * connection eagerly to abort the in-flight backend query.
-         */
-        let released = false;
-        const releaseOnce = (err) => {
-            if (released)
-                return;
-            released = true;
-            try {
-                checkout.release(err);
-            }
-            catch {
-                // pg may throw if the client is already released, swallow.
-            }
-        };
+        if (timeout !== undefined && timeout !== 0 && !(typeof timeout === 'number' && timeout > 0 && timeout < 2 ** 31)) {
+            throw new ValidationError(`$transaction: timeout must be a positive number of milliseconds (or 0 for none), received ${describeValue(timeout)}.`);
+        }
+        return { begin, sessionConfig, timeout: timeout || undefined };
+    }
+    /**
+     * The one transaction lifecycle both `$transaction` forms share, so an option
+     * one form honours is honoured by the other: BEGIN (isolation level, read
+     * only) -> `sessionContext` GUCs -> body, raced against `timeout` -> COMMIT,
+     * and ROLLBACK on any failure.
+     *
+     * The transaction state is ended as soon as the body settles, BEFORE the
+     * COMMIT, so a `tx` that leaked out of the callback can never slip a
+     * statement in ahead of the COMMIT or onto the connection after it. Work the
+     * body started and did not await is caught there too: the transaction rolls
+     * back rather than committing whatever part of it had run.
+     *
+     * A transaction that will not commit (timed out, failed, unawaited work) is
+     * stopped on the server before its connection is released: the running
+     * statement is cancelled and ROLLBACK sent, so its locks are freed now (see
+     * {@link rollbackOnServer}). A connection that cannot be confirmed clean is
+     * destroyed instead of reused.
+     */
+    async runInTransaction(options, body) {
+        const { begin, sessionConfig, timeout } = this.resolveTransactionOptions(options);
+        // openCheckout sends BEGIN once more on a fresh connection when the first
+        // one turns out to be dead, and releases the connection itself when BEGIN
+        // fails for good. So everything below runs in a transaction that began.
+        const { client, checkout } = await openCheckout(this.queryPool, (c) => runTxControl(c, begin));
+        const state = new TransactionState(client, this.dialect, { userTransaction: true });
         let timedOut = false;
         try {
-            // Apply transaction-local session context (RLS / multi-tenant GUCs).
-            // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
-            // user fn. Any error here propagates to the catch below and rolls back
-            // like any other transaction failure. We use set_config(name, value,
-            // is_local=true), the parameterizable, transaction-scoped equivalent of
-            // SET LOCAL, so both name and value are BOUND params, never interpolated.
-            if (options?.sessionContext) {
-                if (!this.dialect.supportsRLS) {
-                    throw new UnsupportedFeatureError('sessionContext (RLS session GUCs)', this.dialect.name, 'set_config-based row-level-security context requires PostgreSQL.');
-                }
-                for (const [name, value] of Object.entries(options.sessionContext)) {
-                    if (!GUC_NAME_REGEX.test(name)) {
-                        throw new ValidationError(`Invalid session-context GUC name "${name}", must match ` +
-                            '/^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)?$/ (optionally namespaced, e.g. "app.current_tenant")');
-                    }
-                    const cfg = this.dialect.buildSetSessionConfig(name, String(value));
-                    await client.query(cfg.sql, cfg.params);
-                }
-            }
-            // Create the transaction client with typed table accessors. Pass the
-            // parent pool so its read-only guard + PowDB capabilities flow into the
-            // transaction-scoped proxy pool (see TransactionClient.createTxPool).
-            const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions, this.pool);
-            // Dynamically attach table accessors to tx
-            for (const tableName of Object.keys(this.schema.tables)) {
-                const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
-                if (!(camelName in tx)) {
-                    Object.defineProperty(tx, camelName, {
-                        get: () => tx.table(tableName),
-                        enumerable: true,
-                    });
-                }
-            }
-            let result;
+            // Transaction-local session context (RLS / multi-tenant GUCs), applied
+            // after BEGIN and before the body via set_config(name, value,
+            // is_local=true), so both name and value are BOUND params.
+            for (const cfg of sessionConfig)
+                await applySessionSetting(client, cfg);
             // Engine seam: when the checked-out connection exposes
-            // wrapTransactionCallback (single-writer engines such as PowDB), run the user
-            // callback through it so the engine can scope its re-entrancy marker to
-            // the callback's async subtree. All other drivers: plain fn(tx).
+            // wrapTransactionCallback (single-writer engines such as PowDB), run the
+            // body through it so the engine can scope its re-entrancy marker to the
+            // body's async subtree. All other drivers: plain body().
             const wrap = client.wrapTransactionCallback;
-            const runCallback = () => (wrap ? wrap.call(client, () => fn(tx)) : fn(tx));
+            const runBody = () => state.enter(() => (wrap ? wrap.call(client, () => body(client, state)) : body(client, state)));
+            let result;
             if (timeout) {
-                // Race between the function and a timeout. If the timeout fires we
-                // need to actually abort the in-flight query, otherwise the backend
-                // keeps running until pg's own timeout, holding a pool slot the whole
-                // time. The simplest reliable cancellation is to destroy the
-                // connection: passing a truthy argument to client.release() tells the
-                // pg pool to discard the client (its socket is closed, which causes
-                // Postgres to abort the active query and roll back the transaction).
-                // The pool will spin up a fresh connection on the next checkout.
                 let timer;
                 const timeoutPromise = new Promise((_, reject) => {
                     timer = setTimeout(() => {
                         timedOut = true;
-                        // Destroy the connection to abort the in-flight backend query.
-                        // We do this BEFORE rejecting so the socket is gone by the time
-                        // the caller's catch block runs.
-                        releaseOnce(new Error('[turbine] Transaction timeout, connection destroyed'));
-                        reject(new TimeoutError(timeout, 'Transaction'));
+                        state.end('timed out');
+                        reject(new TimeoutError(timeout, 'Transaction', {
+                            message: `Transaction timed out after ${timeout}ms and was rolled back, so none of its writes were ` +
+                                'saved. A statement it was running was cancelled on the server.',
+                            outcome: 'not-executed',
+                        }));
                     }, timeout);
                 });
                 try {
-                    result = await Promise.race([runCallback(), timeoutPromise]);
+                    result = await Promise.race([runBody(), timeoutPromise]);
                 }
                 finally {
                     clearTimeout(timer);
                 }
             }
             else {
-                result = await runCallback();
+                result = await runBody();
             }
-            await runTxControl(client, this.dialect.commitStatement());
+            const unawaited = state.busy;
+            state.end('has ended');
+            if (unawaited)
+                throw unawaitedWorkError('$transaction');
+            // A statement inside was cut short by its timeout, and the callback
+            // caught the error: whether it ran is not known, so nothing commits.
+            if (state.abortedWith !== undefined)
+                throw rolledBackError(state.abortedWith, 'transaction');
+            await commitTransaction(client, this.dialect.commitStatement(), state.firstFailure);
+            state.end('committed');
+            checkout.release();
             if (this.logging) {
-                console.log('[turbine] Transaction committed');
+                logTo(this.logger, 'debug', 'Transaction committed', {
+                    code: 'transaction-committed',
+                    operation: '$transaction',
+                });
             }
             return result;
         }
         catch (err) {
-            // If the timeout fired we already destroyed the connection, issuing a
-            // ROLLBACK on a released client would throw "Client has already been
-            // released". Skip the rollback in that case (the backend rolled back
-            // when its socket was closed). A BEGIN that failed never gets here, see
-            // openCheckout above, so there is always a transaction to roll back.
-            if (!timedOut && !released) {
-                try {
-                    await client.query(this.dialect.rollbackStatement());
-                }
-                catch {
-                    // Best-effort rollback, the connection may have died mid-query.
-                }
-            }
+            // A timed-out transaction keeps its 'timed out' wording for any late
+            // statement the callback still tries to send.
+            if (!timedOut)
+                state.end('was rolled back');
+            const clean = await rollbackOnServer(client, state, this.dialect);
+            checkout.release(clean ? undefined : new Error('[turbine] transaction connection discarded: rollback not confirmed'));
             if (this.logging) {
-                console.log('[turbine] Transaction rolled back');
+                logTo(this.logger, 'debug', 'Transaction rolled back', {
+                    code: 'transaction-rolled-back',
+                    operation: '$transaction',
+                });
             }
             throw explainConnectionLoss(err, checkout.lostWith);
         }
-        finally {
-            releaseOnce();
+    }
+    /**
+     * Validate `sessionContext` and build its `set_config` statements, before
+     * any connection is taken.
+     *
+     * A name must be a namespaced custom setting (`app.tenant_id`) unless it is
+     * listed in `allowBuiltinSettings`: an un-dotted name is one of PostgreSQL's
+     * own settings (`role`, `search_path`, `statement_timeout`), and a context
+     * built from request data must not be able to reach one. A value that is not
+     * a string, number or boolean is refused, so a missing tenant id cannot reach
+     * a row-level security policy as the text `'undefined'`.
+     */
+    resolveSessionContext(context, allowBuiltinSettings) {
+        const allowed = resolveBuiltinSettingsAllowlist(allowBuiltinSettings);
+        if (!context)
+            return [];
+        if (!this.dialect.supportsRLS) {
+            throw new UnsupportedFeatureError('sessionContext (RLS session GUCs)', this.dialect.name, 'set_config-based row-level-security context requires PostgreSQL.');
+        }
+        const statements = [];
+        for (const [name, value] of Object.entries(context)) {
+            if (!GUC_NAME_REGEX.test(name)) {
+                throw new ValidationError(`Invalid session-context GUC name "${name}", must match ` +
+                    '/^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)?$/ (optionally namespaced, e.g. "app.current_tenant")');
+            }
+            if (!name.includes('.') && !allowed.has(name.toLowerCase())) {
+                throw new ValidationError(`sessionContext["${name}"] names a PostgreSQL setting, not a custom one. A session context may set ` +
+                    'namespaced custom settings only (`app.tenant_id`, with a dot), because a built-in setting such as ' +
+                    '`role`, `search_path` or `statement_timeout` changes who the transaction runs as or what limits it ' +
+                    `has. Rename it into a namespace, or, if your code sets it on purpose, pass \`allowBuiltinSettings: ['${name}']\`.`);
+            }
+            const kind = typeof value;
+            if (kind !== 'string' && kind !== 'number' && kind !== 'boolean') {
+                throw new ValidationError(`sessionContext["${name}"] is ${value === null ? 'null' : kind}. A session setting is text, and ` +
+                    `${value === undefined ? 'a missing value' : 'this value'} would reach your row-level security ` +
+                    `policies as the string "${String(value)}". Pass a string, number or boolean, and check the value ` +
+                    'your request context supplies.');
+            }
+            statements.push({ name, ...this.dialect.buildSetSessionConfig(name, String(value)) });
         }
+        return statements;
     }
     /**
-     * Execute a batch of {@link DeferredQuery} objects atomically inside one
-     * transaction. Backs the `$transaction([...])` array overload. Reuses the raw
-     * {@link transaction} machinery (BEGIN/COMMIT/ROLLBACK + connection release);
-     * each result is passed through its query's `transform`.
+     * Run a batch of {@link DeferredQuery} objects on a transaction's connection.
+     * Backs the `$transaction([...])` array overload; the transaction itself
+     * (BEGIN/COMMIT/ROLLBACK, options, release) is {@link runInTransaction}'s.
+     * Each result is passed through its query's `transform`.
      *
      * Execution strategy on the single transaction connection:
      *   - **Sequential (default).** Await each statement's reply before sending
@@ -1884,44 +2696,48 @@ export class TurbineClient {
      * rethrowing, which keeps the connection's request/reply pairing intact and
      * means ROLLBACK is only issued once no statement is still in flight.
      */
-    async transactionBatch(queries) {
-        if (queries.length === 0) {
-            return [];
-        }
+    async runBatch(client, state, queries) {
         // One `$on('query')` event per statement, `batch: 'transaction'`, only
-        // when someone is listening; each statement is timed on its own.
+        // when someone is listening; each statement is timed on its own. Every
+        // statement goes through the transaction state, so a timeout can tell
+        // what is still on the wire and stop it.
         const sink = this.queryListeners.size > 0 ? this.queryOptions._onQuery : undefined;
-        const reported = (dq, run) => runReportedStatement(sink, { ...deferredIdentity(dq.tag), batch: 'transaction' }, dq.sql, dq.params, run, wrapPgError);
-        return this.transaction(async (client) => {
-            const pipelined = client.supportsPipelining === true &&
-                this.dialect.resultStrategy !== 'reselect';
-            if (pipelined) {
-                // Dispatch every statement before awaiting any reply. The driver's
-                // FIFO guarantee makes settled[i] the reply to queries[i]. Each
-                // statement is timed from its dispatch to its own reply.
-                const settled = await Promise.allSettled(queries.map((dq) => reported(dq, () => client.query(dq.sql, dq.params))));
-                const results = [];
-                for (let i = 0; i < settled.length; i++) {
-                    const outcome = settled[i];
-                    if (outcome.status === 'rejected') {
-                        throw wrapPgError(outcome.reason);
-                    }
-                    results.push(queries[i].transform(outcome.value));
-                }
-                return results;
-            }
+        // Each statement is sent with its `sqlComment`; its event reports the
+        // commentless text and the comment beside it, as a model call's does.
+        const comments = this.statementComments(queries);
+        const reported = (i, run) => {
+            const dq = queries[i];
+            const comment = comments?.[i];
+            return state.run(() => runReportedStatement(sink, { ...deferredIdentity(dq.tag), batch: 'transaction', ...(comment === undefined ? {} : { comment }) }, dq.sql, dq.params, () => run(commentDeferred(dq, comment)), wrapPgError));
+        };
+        const pipelined = client.supportsPipelining === true &&
+            this.dialect.resultStrategy !== 'reselect';
+        if (pipelined) {
+            // Dispatch every statement before awaiting any reply. The driver's
+            // FIFO guarantee makes settled[i] the reply to queries[i]. Each
+            // statement is timed from its dispatch to its own reply.
+            const settled = await Promise.allSettled(queries.map((_, i) => reported(i, (dq) => client.query(dq.sql, dq.params))));
             const results = [];
-            for (const dq of queries) {
-                // Non-RETURNING engines (resultStrategy 'reselect', e.g. MySQL) attach a
-                // reselect plan that runs the write plus a follow-up SELECT; running
-                // dq.sql alone would transform a row-less write result.
-                const raw = await reported(dq, () => this.dialect.resultStrategy === 'reselect' && dq.reselect
-                    ? dq.reselect((sql, params) => client.query(sql, params))
-                    : client.query(dq.sql, dq.params));
-                results.push(dq.transform(raw));
+            for (let i = 0; i < settled.length; i++) {
+                const outcome = settled[i];
+                if (outcome.status === 'rejected') {
+                    throw wrapPgError(outcome.reason);
+                }
+                results.push(queries[i].transform(outcome.value));
             }
             return results;
-        });
+        }
+        const results = [];
+        for (let i = 0; i < queries.length; i++) {
+            // Non-RETURNING engines (resultStrategy 'reselect', e.g. MySQL) attach a
+            // reselect plan that runs the write plus a follow-up SELECT; running
+            // dq.sql alone would transform a row-less write result.
+            const raw = await reported(i, (dq) => this.dialect.resultStrategy === 'reselect' && dq.reselect
+                ? dq.reselect((sql, params) => client.query(sql, params))
+                : client.query(dq.sql, dq.params));
+            results.push(queries[i].transform(raw));
+        }
+        return results;
     }
     /**
      * Convenience wrapper around `$transaction` for the multi-tenant / RLS case:
@@ -1970,7 +2786,8 @@ export class TurbineClient {
      * ends it instead. Postgres does not hold notifications for a disconnected
      * listener, so anything sent during the gap is lost: use
      * `options.onReconnect` to resynchronise. `options.onError` receives the loss
-     * and each failed attempt (default: one `console.error` line each).
+     * and each failed attempt (default: one log line each through `logger`, at
+     * `warn` while it reconnects and `error` once it stops).
      *
      * @example
      * ```ts
@@ -1991,11 +2808,11 @@ export class TurbineClient {
         validateChannel(channel);
         const quoted = quoteIdent(channel);
         if (this.logging) {
-            console.log(`[turbine] LISTEN ${quoted}`);
+            logTo(this.logger, 'debug', `LISTEN ${quoted}`, { code: 'listen', channel });
         }
         const sub = await createSubscription(this.pool, channel, quoted, handler, (closed) => {
             this.activeSubscriptions.delete(closed);
-        }, options);
+        }, options, this.logger);
         this.activeSubscriptions.add(sub);
         return sub;
     }
@@ -2018,7 +2835,7 @@ export class TurbineClient {
         }
         validateChannel(channel);
         if (this.logging) {
-            console.log(`[turbine] NOTIFY ${channel}`);
+            logTo(this.logger, 'debug', `NOTIFY ${channel}`, { code: 'notify', channel });
         }
         try {
             await this.pool.query('SELECT pg_notify($1, $2)', [channel, payload ?? '']);
@@ -2056,29 +2873,45 @@ export class TurbineClient {
      * Throws if the connection fails.
      */
     async connect() {
-        // A connection the server closed while idle says nothing about whether
-        // the database is reachable, so the check runs on a fresh one when the
-        // first turns out to be dead (see openCheckout).
+        await this.roundTrip();
+        if (this.logging) {
+            logTo(this.logger, 'debug', 'Connection verified', { code: 'connection-verified' });
+        }
+    }
+    /**
+     * Run one cheap round trip (`SELECT 1`) on the primary and resolve with its
+     * latency in milliseconds, for health checks and for setting
+     * `autoRoundTripMs`. The time measures the statement on a checked-out
+     * connection, not the wait for one: an exhausted pool rejects with
+     * `ConnectionError` (E004) after `connectionTimeoutMs` instead. Rejects with
+     * the typed connection error when the database cannot be reached.
+     */
+    async $ping() {
+        return this.roundTrip();
+    }
+    /**
+     * `SELECT 1` on a checked-out primary connection, timed. A connection the
+     * server closed while idle says nothing about whether the database is
+     * reachable, so it runs on a fresh one when the first turns out to be dead
+     * (see openCheckout).
+     */
+    async roundTrip() {
+        let latency = 0;
         const { checkout } = await openCheckout(this.pool, async (client) => {
+            const start = performance.now();
             try {
                 await client.query('SELECT 1');
             }
             catch (err) {
                 throw wrapPgError(err);
             }
+            latency = performance.now() - start;
         });
         checkout.release();
-        if (this.logging) {
-            console.log('[turbine] Connection verified');
-        }
+        return latency;
     }
-    /**
-     * Gracefully shut down the connection pool.
-     *
-     * If Turbine was given an external pool via `TurbineConfig.pool`, this
-     * method is a no-op, the caller is responsible for the pool's lifecycle.
-     */
-    async disconnect() {
+    async disconnect(options) {
+        const timeoutMs = resolveNonNegativeInteger(options?.timeoutMs, 'disconnect timeoutMs', 'milliseconds');
         // Tear down any live LISTEN subscriptions first. Each holds a dedicated
         // pooled connection checked out; if we ended the pool (or returned for an
         // external pool) without releasing them, pool.end() would wait forever for
@@ -2094,33 +2927,63 @@ export class TurbineClient {
             }
             this.activeSubscriptions.clear();
         }
-        // Close owned (string-configured) replica pools regardless of whether the
-        // primary is owned, external replica pools are left untouched (caller owns
-        // their lifecycle), same contract as an external primary.
-        for (const replicaPool of this.ownedReplicaPools) {
-            try {
-                await replicaPool.end();
-            }
-            catch (err) {
-                if (this.logging) {
-                    console.error('[turbine] Error closing replica pool:', err.message);
-                }
+        // Owned (string-configured) replica pools are closed whether or not the
+        // primary is owned; external replica pools are the caller's, like an
+        // external primary.
+        const endReplicas = Promise.all(this.ownedReplicaPools.map((replicaPool) => replicaPool.end().catch((err) => {
+            if (this.logging) {
+                logTo(this.logger, 'error', `Error closing replica pool: ${err.message}`, {
+                    code: 'replica-close-error',
+                    error: err,
+                });
             }
+        })));
+        if (!this.ownsPool && this.logging) {
+            logTo(this.logger, 'debug', 'disconnect() skipped, external primary pool is not owned by Turbine', {
+                code: 'disconnect-skipped',
+            });
         }
-        if (!this.ownsPool) {
-            if (this.logging) {
-                console.log('[turbine] disconnect() skipped, external primary pool is not owned by Turbine');
+        const ending = Promise.all([endReplicas, this.ownsPool ? this.pool.end() : undefined]);
+        if (timeoutMs === undefined || (await settlesWithin(ending, timeoutMs))) {
+            await ending;
+            if (this.logging && this.ownsPool) {
+                logTo(this.logger, 'debug', 'Pool disconnected', { code: 'pool-disconnected', timedOut: false });
             }
-            return;
+            return options === undefined ? undefined : { timedOut: false, forcedConnections: 0 };
         }
-        await this.pool.end();
+        const forcedConnections = await this.forceCloseCheckedOut();
+        // Closed connections reach the pool as their holders' queries fail; give
+        // that one grace period, then return either way rather than hang on a
+        // holder that never releases.
+        await settlesWithin(ending, TX_ABORT_GRACE_MS);
         if (this.logging) {
-            console.log('[turbine] Pool disconnected');
+            logTo(this.logger, 'debug', `Pool disconnected after ${timeoutMs}ms, ${forcedConnections} connection(s) closed in use`, { code: 'pool-disconnected', timedOut: true, timeoutMs, forcedConnections });
         }
+        return { timedOut: true, forcedConnections };
     }
-    /** Alias for disconnect() */
-    async end() {
-        return this.disconnect();
+    /**
+     * Cancel the running statement of every connection still checked out of a
+     * pool this client opened, then close the connection. Cancelling first is
+     * what stops the work on the server: a closed socket alone is noticed only
+     * when the backend next writes to it. Returns how many were closed.
+     */
+    async forceCloseCheckedOut() {
+        const clients = this.checkoutWatches.flatMap((watch) => [...watch.checkedOut]);
+        await Promise.all(clients.map(async (client) => {
+            await sendCancelRequest(client, TX_ABORT_GRACE_MS);
+            const c = client;
+            const closing = Promise.resolve()
+                .then(() => c.end?.())
+                .catch(() => { });
+            // A backend that does not answer the terminate message within the
+            // grace period has its socket destroyed instead.
+            if (!(await settlesWithin(closing, TX_ABORT_GRACE_MS)))
+                c.connection?.stream?.destroy?.();
+        }));
+        return clients.length;
+    }
+    async end(options) {
+        return options === undefined ? this.disconnect() : this.disconnect(options);
     }
     /**
      * Pool statistics for monitoring. Returns zeros for pools that don't
@@ -2134,3 +2997,15 @@ export class TurbineClient {
         };
     }
 }
+// What prisma-compat (and anything else that wraps a client) logs through: the
+// client's logger and resolved diagnostics, under a `Symbol.for` key so a CJS
+// and an ESM copy agree. Defined outside the class body so it stays off the
+// published declaration of `TurbineClient`.
+Object.defineProperty(TurbineClient.prototype, CLIENT_LOG_CONTEXT, {
+    get() {
+        const self = this;
+        return { logger: self.logger, diagnostics: self.diagnostics };
+    },
+    enumerable: false,
+    configurable: false,
+});