turbine-orm 0.81.0 → 0.90.0

package/dist/client.d.ts

@@ -21,14 +21,18 @@
  * const users = db.table<User>('users');
  * ```
  */
+import { type DiagnosticsConfig } from './diagnostics.js';
 import { type Dialect } from './dialect.js';
 import { type ErrorMessageMode } from './errors.js';
+import { type TurbineLogger } from './logger.js';
 import { type ObserveConfig, type ObserveHandle } from './observe.js';
 import type { PgCompatPool, PgCompatPoolClient } from './pg-types.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
 import { type DeferredQuery, type GlobalFilters, type JsonEncoding, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy, type TemporalInfinityReading } from './query/index.js';
+import { type SqlCommentOptions } from './query/sql-comment.js';
 import { type ListenOptions, type NotificationHandler, type Subscription } from './realtime.js';
 import type { SchemaMetadata } from './schema.js';
+import { type TransactionScope, TransactionState } from './transaction-state.js';
 import { TypedSqlQuery } from './typed-sql.js';
 export interface RetryOptions {
     maxAttempts?: number;
@@ -74,54 +78,103 @@ export interface TurbineConfig {
      * like `@neondatabase/serverless`, `@vercel/postgres`, or any other pg-API
      * compatible pool. When provided, all connection-string fields are ignored
      * and Turbine will NOT create its own pg.Pool.
+     *
+     * Turbine's own queries on it read `bigint` as a number and, under
+     * {@link utcTimestamps}, zone-less temporals as UTC, by attaching parsers to
+     * each query (node-postgres' query-level `types`). Your own queries on the
+     * pool, and the pg module's parser table, are left alone. A driver that does
+     * not read a query's `types` keeps its own readings, as does every driver on
+     * the `edge-light` / `browser` builds, where Turbine has no parsers to attach.
      */
-    pool?: PgCompatPool;
+    pool?: PgCompatPool | undefined;
     /** Postgres connection string (e.g. postgres://user:pass@host:5432/db) */
-    connectionString?: string;
+    connectionString?: string | undefined;
     /** Host (used if connectionString is not set) */
-    host?: string;
+    host?: string | undefined;
     /** Port (default: 5432) */
-    port?: number;
+    port?: number | undefined;
     /** Database name */
-    database?: string;
+    database?: string | undefined;
     /** Username */
-    user?: string;
+    user?: string | undefined;
     /** Password */
-    password?: string;
+    password?: string | undefined;
     /** SSL/TLS options for the connection (required for most cloud providers) */
     ssl?: boolean | {
-        rejectUnauthorized?: boolean;
-        ca?: string;
-        key?: string;
-        cert?: string;
-    };
+        rejectUnauthorized?: boolean | undefined;
+        ca?: string | undefined;
+        key?: string | undefined;
+        cert?: string | undefined;
+    } | undefined;
     /** Maximum number of connections in the pool (default: 10) */
-    poolSize?: number;
+    poolSize?: number | undefined;
     /** Idle timeout in ms before a connection is closed (default: 30000) */
-    idleTimeoutMs?: number;
+    idleTimeoutMs?: number | undefined;
     /** Connection timeout in ms (default: 5000) */
-    connectionTimeoutMs?: number;
+    connectionTimeoutMs?: number | undefined;
     /** pg-style alias for {@link poolSize}; the explicit field wins when both are set. */
-    max?: number;
+    max?: number | undefined;
     /** pg-style alias for {@link idleTimeoutMs}; the explicit field wins when both are set. */
-    idleTimeoutMillis?: number;
+    idleTimeoutMillis?: number | undefined;
     /** pg-style alias for {@link connectionTimeoutMs}; the explicit field wins when both are set. */
-    connectionTimeoutMillis?: number;
-    /** Enable query logging to console (default: false) */
-    logging?: boolean;
+    connectionTimeoutMillis?: number | undefined;
+    /**
+     * Emit Turbine's lifecycle lines (pool created, raw SQL preview, transaction
+     * committed, ...) at the logger's `debug` level, plus the errors a throwing
+     * `$on` listener raises. Default: false. With the default logger the lines
+     * go to `console`. Bound parameter values are never logged.
+     */
+    logging?: boolean | undefined;
+    /**
+     * Where Turbine's log lines go. Each line is a message plus a structured
+     * entry whose `code` is stable (`'pool-error'`, `'unknown-config-key'`); the
+     * message text is not. Every method is optional and a missing one drops that
+     * level, so `{}` silences Turbine entirely. Default: `console`, each line
+     * prefixed `[turbine]`.
+     *
+     * The arguments are `(message, entry)`, like `console` and winston. For pino
+     * or bunyan, which take `(object, message)`, adapt:
+     * `{ warn: (msg, e) => log.warn(e, msg), error: (msg, e) => log.error(e, msg) }`.
+     *
+     * No line carries a bound parameter value, whatever `logQueryParams` says.
+     * Once-per-process warnings are deduplicated process-wide, so a warning one
+     * client already emitted does not reach a second client's logger.
+     */
+    logger?: TurbineLogger | undefined;
+    /**
+     * What Turbine checks and says about itself: per-query advice (unknown
+     * options, unordered pages, missing FK indexes, ...) and the SQL-cache
+     * self-check. `'development'` turns both on; `'production'` turns both off.
+     * An object overrides either part: `{ mode: 'production', cacheCheck: {
+     * sample: 0.001 } }`.
+     *
+     * Default: `'production'` when `NODE_ENV` is `'production'` when the client is
+     * constructed (or when there is no `process`, as on an edge runtime), else
+     * `'development'`. Read once, at construction. Set it explicitly on a worker
+     * or serverless function that does not set `NODE_ENV`.
+     *
+     * Construction warnings (a misspelled config key, an option an external pool
+     * ignores, prepared statements behind a pooler) do not depend on it: they
+     * describe production hazards, fire once per process, and are always on.
+     */
+    diagnostics?: DiagnosticsConfig | undefined;
     /** Default LIMIT applied to findMany() when no limit is specified (opt-in, default: undefined) */
-    defaultLimit?: number;
+    defaultLimit?: number | undefined;
     /**
      * Log a warning when findMany() is called without a limit (default: false).
      * Pass a per-table map (`{ users: false }`) to override the default for
      * specific tables; per-call `warnOnUnlimited` on findMany args wins over both.
      */
-    warnOnUnlimited?: boolean | Record<string, boolean>;
+    warnOnUnlimited?: boolean | Record<string, boolean> | undefined;
     /**
      * Interpret Postgres `timestamp` (without time zone) values as UTC, both
      * at the driver level (type parsers for OIDs 1114 `timestamp`, 1082 `date`,
-     * and their array forms 1115 / 1182, registered only when Turbine owns the
-     * pool) and when coercing nested-relation JSON dates. A `date` column is
+     * and their array forms 1115 / 1182) and when coercing nested-relation JSON
+     * dates. The parsers are registered on the pg module when Turbine owns the
+     * pool; on a pool you supply they are attached to each of Turbine's own
+     * queries instead, and your own queries on that pool keep your parsers. A
+     * bound `Date` in `raw` / `rawUnsafe` / `sql` is sent as its UTC fields under
+     * this setting, so it reads back unchanged from a zone-less column. A `date` column is
      * zone-less too, so it reads back as UTC midnight rather than the process's
      * local midnight. This is the
      * Prisma/Rails/Django convention and makes results independent of the
@@ -146,15 +199,13 @@ export interface TurbineConfig {
      * `ValidationError` rather than handing back a client whose writes and reads
      * disagree. Give every
      * client in the process the same value, or isolate the odd one in its own
-     * process. A client on an EXTERNAL pool never REGISTERS a parser (it inherits
-     * whatever configuration the caller's driver has, so a process containing
-     * only external-pool clients is untouched), but it does take part in the
-     * agreement check: registration is process-global, so once a Turbine-owned
-     * client has installed the parsers an external-pool client reads through them
-     * too, and a disagreeing one would write local `date` literals while reading
-     * UTC.
+     * process. A client on an EXTERNAL pool never REGISTERS a parser (a process
+     * containing only external-pool clients keeps the pg module untouched), but
+     * it does take part in the agreement check: with `false` it reads through the
+     * pg module's table, which a Turbine-owned client may have set to UTC, and
+     * would then write local `date` literals while reading UTC.
      */
-    utcTimestamps?: boolean;
+    utcTimestamps?: boolean | undefined;
     /**
      * How a Postgres temporal `infinity` / `-infinity` is handed back:
      * `'preserve'` (the default, the JS numbers `Infinity` / `-Infinity`) or
@@ -177,11 +228,11 @@ export interface TurbineConfig {
      * strategy, every write projection, `groupBy` keys and `_min` / `_max`.
      *
      * Leaving the option unset selects `'preserve'` AND enables a one-time
-     * warning (per process, per field, not silenced by `NODE_ENV=production`) the
+     * warning (per process, per field, not silenced by `diagnostics: 'production'`) the
      * first time a stored infinity is actually read, describing that reading and
      * both escapes. Naming either reading explicitly silences it.
      */
-    temporalInfinity?: TemporalInfinityReading;
+    temporalInfinity?: TemporalInfinityReading | undefined;
     /**
      * Pin `plan_cache_mode` on every connection this client opens, fixing how the
      * PostgreSQL backend chooses between a custom plan (re-planned per parameter
@@ -279,7 +330,101 @@ export interface TurbineConfig {
      * `ignore_startup_parameters`). Set it on the role or server there
      * (`ALTER ROLE ... SET plan_cache_mode = ...`) instead.
      */
-    planCacheMode?: PlanCacheMode;
+    planCacheMode?: PlanCacheMode | undefined;
+    /**
+     * A server-side ceiling, in milliseconds, on every statement this client's
+     * connections run: PostgreSQL's `statement_timeout`. A statement that runs
+     * longer is cancelled by the server, which rolls back its effect and frees the
+     * connection, and it rejects with `TimeoutError` (E002, `outcome:
+     * 'not-executed'`). It bounds what a per-query `timeout` cannot reach: a
+     * forgotten query, a stream's `FETCH`, a statement inside `$transaction`.
+     *
+     * Applied as the `options=-c statement_timeout=...` connection parameter on
+     * pools Turbine opens (the primary and string `replicas`), so it is in force
+     * from each connection's first statement and nothing is ever `SET` on a
+     * session. `0` sends `statement_timeout=0`, which disables a timeout the
+     * server or role would otherwise apply. Unset (the default) sends nothing.
+     *
+     * Must be a non-negative integer (E003). PostgreSQL only (E017 elsewhere). An
+     * external `pool` is not touched: the option is then a no-op with a one-time
+     * dev warning, and the driver's own connection setup should set the GUC. A
+     * connection pooler may refuse startup parameters (PgBouncer's
+     * `ignore_startup_parameters`); set it on the role there instead
+     * (`ALTER ROLE app SET statement_timeout = '30s'`).
+     */
+    statementTimeoutMs?: number | undefined;
+    /**
+     * Close a pooled connection once it is this many seconds old, when it is
+     * next idle, and open a fresh one on demand. Default `1800` (30 minutes) on
+     * pools Turbine opens; `0` keeps connections for as long as they are in use.
+     *
+     * Recycling bounds what a long-lived server session accumulates: the
+     * prepared statements and their cached plans, catalog caches, and memory a
+     * backend keeps after a large query. It also moves connections onto a new
+     * server after a DNS failover or a replica scale-out. A connection that is
+     * checked out is never closed under its holder; it is retired when it comes
+     * back. Must be a non-negative integer (E003). Ignored, with a one-time dev
+     * warning, on an external `pool`.
+     */
+    maxLifetimeSeconds?: number | undefined;
+    /**
+     * Close a cursor stream (`findManyStream`, `findManyStreamBatches`) and
+     * release its connection once its consumer has asked for nothing for this
+     * many milliseconds. Default `300000` (five minutes); `0` disables. A stream
+     * call's own `idleTimeoutMs` overrides it.
+     *
+     * A consumer that stops pulling without calling `return()` (an iterator that
+     * is stored and forgotten, a response stream torn down without propagating)
+     * would otherwise hold a pooled connection forever and, on PostgreSQL, an
+     * open transaction whose snapshot holds back vacuum for the whole database.
+     * On expiry Turbine closes the cursor, releases the connection, and logs
+     * `stream-idle-timeout`; the next pull, if one comes, throws `TimeoutError`
+     * (E002). Only streams that hold a connection between pulls are watched.
+     *
+     * On PostgreSQL the stream's own transaction also gets a server-side limit,
+     * `idle_in_transaction_session_timeout` at this value plus 10 seconds
+     * (transaction-local, never a session `SET`; a stricter setting already in
+     * force is kept), so a process that stops running timers (frozen between
+     * serverless invocations) cannot hold the transaction open either. Must be a
+     * whole number of milliseconds (E003).
+     */
+    streamIdleTimeoutMs?: number | undefined;
+    /**
+     * Append sqlcommenter-style key/values to every statement this client builds,
+     * so `pg_stat_activity`, the server log, `auto_explain` and database APM
+     * tools can attribute a statement to a service, model, feature or trace:
+     *
+     * ```sql
+     * SELECT ... /*action='findMany',application='billing',model='users',tag='checkout'*\/
+     * ```
+     *
+     * `static` adds constant pairs, `model: true` the table and operation,
+     * `tag: true` the label of the innermost `db.$tag(label, fn)`, and `dynamic`
+     * per-statement pairs computed in the caller's async context (a W3C
+     * `traceparent`). Keys are lower-case `[a-z][a-z0-9_]*`; values are
+     * URL-encoded (so none can end or nest the comment) and at most 256
+     * characters. A malformed `static` key or value is E003 here; a bad
+     * `dynamic` one is left out with a `sql-comment-dropped` warning, never
+     * thrown.
+     *
+     * Model statements get it: reads, writes, streams, pipelines and
+     * `$transaction` batches. Raw SQL, transaction control and `set_config`
+     * calls do not. It is added after the SQL-template cache, so caching is
+     * unchanged, and `$on('query')` events keep `sql` commentless and carry the
+     * comment as `comment`.
+     *
+     * Prepared statements: a statement whose comment is static, model or tag is
+     * still prepared, under a name of its own (counted against the same budget
+     * as every other name). One carrying any `dynamic` value is sent unnamed,
+     * so it is parsed and planned on every execution (tens of microseconds per
+     * statement on a local PostgreSQL, more for nested reads): return dynamic
+     * values only when they are worth that, for example only for sampled traces.
+     *
+     * Refused (E017) on PowDB, which runs no SQL, and `dynamic` on MySQL, whose
+     * engine keeps a server-side prepared statement per distinct text and would
+     * exhaust the server's `max_prepared_stmt_count`.
+     */
+    sqlComment?: SqlCommentOptions | undefined;
     /**
      * Refuse a nested `connect` / `connectOrCreate` that would re-parent a
      * to-many child already owned by a different parent. Off by default,
@@ -290,7 +435,7 @@ export interface TurbineConfig {
      * take another tenant's row. See
      * {@link import('./nested-write.js').NestedWriteContext.scopedConnect}.
      */
-    scopedConnect?: boolean;
+    scopedConnect?: boolean | undefined;
     /**
      * Default strategy for resolving `with`-clause relations, applied to every
      * `findMany`/`findUnique`/`findFirst` unless overridden per query.
@@ -313,7 +458,7 @@ export interface TurbineConfig {
      * batched loaders (an ineligible relation falls back to them silently even
      * under `'join'`; `'auto'` resolves to PowDB's own default).
      */
-    relationLoadStrategy?: RelationLoadStrategy;
+    relationLoadStrategy?: RelationLoadStrategy | undefined;
     /**
      * When `true`, every to-many `with` relation with no explicit `orderBy` is
      * loaded ordered by the target table's primary key ascending, so unordered
@@ -323,7 +468,7 @@ export interface TurbineConfig {
      * `stableRelationOrder` overrides this. Default `false` (SQL is byte-identical
      * when off). SQL engines only. See {@link RelationLoadStrategy}.
      */
-    stableRelationOrder?: boolean;
+    stableRelationOrder?: boolean | undefined;
     /**
      * When `true`, a `findMany` that paginates (`limit` / `take` / `offset`) but
      * declares no `orderBy` is ordered by the table's primary key ascending
@@ -341,7 +486,7 @@ export interface TurbineConfig {
      * emitted SQL is byte-identical to before, and a dev-mode warning points at
      * the affected queries.
      */
-    implicitPkOrdering?: boolean;
+    implicitPkOrdering?: boolean | undefined;
     /**
      * Parent-row ceiling for the `relationLoadStrategy: 'auto'` to-one rule: a
      * to-one relation stays in the single-statement join when the query's `limit`
@@ -349,7 +494,7 @@ export interface TurbineConfig {
      * query is unbounded or bounded above it. Defaults to 1000 (see
      * `AUTO_TO_ONE_JOIN_MAX_ROWS`). Only consulted under `'auto'`.
      */
-    autoToOneJoinMaxRows?: number;
+    autoToOneJoinMaxRows?: number | undefined;
     /**
      * Round-trip time to the database, in milliseconds, used to DERIVE the
      * `relationLoadStrategy: 'auto'` to-one threshold instead of guessing a row
@@ -363,7 +508,7 @@ export interface TurbineConfig {
      * which reproduces the historical 1000-row threshold exactly. Overridden by
      * an explicit `autoToOneJoinMaxRows`; only consulted under `'auto'`.
      */
-    autoRoundTripMs?: number;
+    autoRoundTripMs?: number | undefined;
     /**
      * How nested-relation subqueries encode each row's JSON.
      *
@@ -391,7 +536,7 @@ export interface TurbineConfig {
      * `relationLoadStrategy: 'flatten'`, which is refused while positional is
      * active because a flattened relation emits no JSON to encode.
      */
-    jsonEncoding?: JsonEncoding;
+    jsonEncoding?: JsonEncoding | undefined;
     /**
      * Controls how `NotFoundError` (and other where-aware errors) format their
      * messages.
@@ -405,7 +550,7 @@ export interface TurbineConfig {
      * The full `where` object is always available as `err.where` for
      * programmatic access regardless of mode.
      */
-    errorMessages?: ErrorMessageMode;
+    errorMessages?: ErrorMessageMode | undefined;
     /**
      * Whether `$on('query')` listeners receive the real bound parameter values.
      *
@@ -422,13 +567,19 @@ export interface TurbineConfig {
      * events while keeping error MESSAGES redacted, which is the combination
      * that was previously unreachable.
      */
-    logQueryParams?: boolean;
+    logQueryParams?: boolean | undefined;
     /**
      * Enable prepared statements. Queries are submitted with `{ name, text, values }`
      * to the pg driver, which caches the parse+plan on the server per connection.
      *
      * Default: `true` for Turbine-owned pools, `false` for external pools (serverless
-     * drivers may not support named statements).
+     * drivers may not support named statements) and for a connection string that
+     * names a connection pooler (a `pooler` / `pgbouncer` host, or port 6432 or
+     * 6543). A transaction-mode pooler runs each transaction on any server
+     * connection, so a statement named on one is missing (or already present) on
+     * the next, unless the pooler tracks prepared statements (PgBouncer 1.21+
+     * with `max_prepared_statements` above 0). Set `true` on such a pooler only
+     * when it does; Turbine warns once in development when you do.
      *
      * Override with `TURBINE_DISABLE_PREPARED=1` env var.
      *
@@ -444,14 +595,14 @@ export interface TurbineConfig {
      * through a fixed allowlist or set this to `false`. Documented for readers at
      * https://turbineorm.dev/queries#client-escape-hatches
      */
-    preparedStatements?: boolean;
+    preparedStatements?: boolean | undefined;
     /**
      * Enable the SQL template cache. Repeated queries with the same shape reuse
      * cached SQL text instead of rebuilding from scratch.
      *
      * Default: `true`. Set to `false` as a nuclear kill switch.
      */
-    sqlCache?: boolean;
+    sqlCache?: boolean | undefined;
     /**
      * Maximum number of distinct SQL templates each per-table LRU cache retains.
      *
@@ -461,9 +612,9 @@ export interface TurbineConfig {
      * memory; lower it to cap memory. `0` disables caching entirely (identical to
      * `sqlCache: false`); a negative value is ignored (treated as the default).
      */
-    sqlCacheSize?: number;
+    sqlCacheSize?: number | undefined;
     /** SQL dialect implementation. Defaults to PostgreSQL. Internal Phase-1 seam for dialect packages. */
-    dialect?: Dialect;
+    dialect?: Dialect | undefined;
     /**
      * Read replicas. When set, read-only operations issued outside a transaction
      * (`findMany`, `findFirst`, `findUnique`, `*OrThrow`, `count`, `aggregate`,
@@ -485,7 +636,7 @@ export interface TurbineConfig {
      * without replication lag. Omitting `replicas` (or passing `[]`) leaves the
      * default single-pool path completely unchanged.
      */
-    replicas?: readonly (string | PgCompatPool)[];
+    replicas?: readonly (string | PgCompatPool)[] | undefined;
     /**
      * Automatic WHERE filters applied to every query, keyed by table accessor
      * (`db[name]`). Each value is AND-merged into the compiled WHERE of every
@@ -511,7 +662,7 @@ export interface TurbineConfig {
      * }});
      * ```
      */
-    globalFilters?: GlobalFilters;
+    globalFilters?: GlobalFilters | undefined;
 }
 /** Parameters passed to middleware functions */
 export interface MiddlewareParams {
@@ -543,6 +694,13 @@ export interface TransactionOptions {
      * bound parameters (never interpolated); the GUC name is additionally
      * validated against a strict identifier regex.
      *
+     * Names must be namespaced custom settings (`app.current_tenant`, with a
+     * dot). A name without a dot is one of PostgreSQL's own settings (`role`,
+     * `search_path`, `statement_timeout`, `session_authorization`), which can
+     * change who the transaction runs as or lift its limits, so it is refused
+     * (E003) unless listed in {@link allowBuiltinSettings}. An application that
+     * maps request data into the context then cannot be steered into setting one.
+     *
      * @example
      * ```ts
      * await db.$transaction(
@@ -555,21 +713,71 @@ export interface TransactionOptions {
      * ```
      */
     sessionContext?: Record<string, string | number | boolean>;
+    /**
+     * PostgreSQL's own settings that {@link sessionContext} may set, by name
+     * (`['statement_timeout']`). Every other name in `sessionContext` must be a
+     * namespaced custom setting. List only what the code itself chooses to set,
+     * never a name taken from a request.
+     */
+    allowBuiltinSettings?: readonly string[];
+    /**
+     * Run the transaction READ ONLY (`BEGIN READ ONLY` on PostgreSQL, `START
+     * TRANSACTION READ ONLY` on MySQL): any write inside it is refused by the
+     * server. Use it for multi-statement reads that must see one consistent
+     * snapshot (with `isolationLevel: 'RepeatableRead'`) and must not write.
+     * Other engines have no read-only transaction and throw
+     * `UnsupportedFeatureError` (E017).
+     */
+    readOnly?: boolean;
+}
+/** Which of a client's pools a pool event came from. */
+export interface PoolEventOrigin {
+    /** `'primary'`, or `'replica'` for one of the string `replicas`. */
+    pool: 'primary' | 'replica';
+    /** Index into `replicas` when `pool` is `'replica'`. */
+    replica?: number;
+}
+/** A pool lifecycle event: the connection's error, and the pool it belonged to. */
+export interface PoolEvent extends PoolEventOrigin {
+    /** The driver's error: a server restart, an administrator's terminate, a network drop. */
+    error: Error;
 }
 /**
- * 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).
+ * `$on('poolError')`: an IDLE connection in a pool this client opened failed,
+ * and the pool discarded it. No query was affected. Without a listener the
+ * error is logged at `error` level (code `'pool-error'`), through `logger`.
  */
+export type PoolErrorEvent = PoolEvent;
 /**
- * Operations that may be served by a read replica.
+ * `$on('connectionLost')`: a connection failed while CHECKED OUT, so the query,
+ * stream or transaction using it rejected (with `ConnectionError`, E004).
+ * Emitted once per connection, for pools this client opened.
+ */
+export type ConnectionLostEvent = PoolEvent;
+export interface DisconnectOptions {
+    /**
+     * Stop waiting for checked-out connections after this many milliseconds.
+     * Statements still running then are cancelled on the server and their
+     * connections closed, so a transaction among them rolls back. Without it,
+     * `disconnect()` waits for every connection to be returned.
+     */
+    timeoutMs?: number | undefined;
+}
+export interface DisconnectResult {
+    /** True when connections were still checked out at the deadline and were closed. */
+    timedOut: boolean;
+    /** How many checked-out connections were cancelled and closed at the deadline. */
+    forcedConnections: number;
+}
+/**
+ * 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).
  *
- * 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.
+ * 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.
  */
@@ -578,6 +786,10 @@ export declare const READ_OPERATIONS: ReadonlySet<string>;
  * 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 declare class TransactionClient {
     private readonly client;
@@ -595,9 +807,19 @@ export declare class TransactionClient {
      */
     private readonly sourcePool?;
     private readonly tableCache;
-    private savepointCounter;
     /** Active SQL dialect, owns savepoint keywords and raw-SQL placeholders. */
     private readonly dialect;
+    /** Open/closed state, first failure and savepoint blocks, shared by everything this client hands out. */
+    private readonly 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.
+     */
+    private readonly scope;
+    /** What {@link $connection} hands out, built on first use. */
+    private connectionHandle?;
     constructor(client: PgCompatPoolClient, schema: SchemaMetadata, middlewares: Middleware[], queryOptions?: QueryInterfaceOptions | undefined, 
     /**
      * The parent pool this transaction runs on. Only its `readonly` and
@@ -611,21 +833,83 @@ export declare class TransactionClient {
     sourcePool?: {
         readonly readonly?: boolean;
         readonly capabilities?: unknown;
-    } | undefined);
+    } | undefined, 
+    /**
+     * 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?: TransactionState, 
+    /** The nested block this handle belongs to; omitted for the transaction's own handle. */
+    scope?: TransactionScope);
     /**
      * Get a QueryInterface for a table within this transaction.
      * Uses the dedicated transaction connection instead of the pool.
      */
     table<T extends object = Record<string, unknown>>(name: string): QueryInterface<T>;
+    /**
+     * 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.
+     */
+    $connection(): PgCompatPoolClient;
     /**
      * Execute a nested transaction via SAVEPOINT.
-     * If the inner function throws, only the savepoint is rolled back.
+     *
+     * 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).
      */
     $transaction<R>(fn: (tx: TransactionClient) => Promise<R>): Promise<R>;
+    /** A handle on the same transaction bound to nested block `scope`. */
+    private inScope;
     /**
-     * Execute a raw SQL query within this transaction.
+     * Execute a raw SQL query within this transaction, as a tagged template:
+     * every `${value}` is sent as a bound parameter.
      */
     raw<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    /**
+     * 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).
+     */
+    rawUnsafe<T extends Record<string, unknown> = Record<string, unknown>>(text: string, ...values: unknown[]): Promise<T[]>;
+    /**
+     * 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<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): TypedSqlQuery<T>;
+    private runRaw;
+    /** Bound Dates as UTC text on a PostgreSQL client reading temporal types as UTC. */
+    private rawParams;
     /**
      * @internal The `turbine-orm/prisma-compat` adapter's transaction seam. NOT
      * application API: use {@link raw}, whose tagged template makes concatenating
@@ -663,7 +947,8 @@ export declare 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.
      */
     private createTxPool;
 }
@@ -681,6 +966,13 @@ export declare class TurbineClient {
      * `db.pool as unknown as Pool`.
      */
     readonly pool: PgCompatPool;
+    /**
+     * 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.
+     */
+    private readonly queryPool;
     /** The schema metadata this client was built from */
     readonly schema: SchemaMetadata;
     private static int8ParserRegistered;
@@ -708,6 +1000,10 @@ export declare class TurbineClient {
      */
     private static utcTimestampParsersRegistered;
     private readonly logging;
+    /** Where this client's log lines go (the `logger` option, else console). */
+    private readonly logger;
+    /** The `diagnostics` option, resolved once at construction. */
+    private readonly diagnostics;
     /** Active SQL dialect, owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
     private readonly dialect;
     /** Validated `plan_cache_mode` to pin on every owned connection, or undefined to issue nothing. */
@@ -716,6 +1012,8 @@ export declare class TurbineClient {
     private readonly middlewares;
     private readonly queryListeners;
     private queryOptions;
+    /** The resolved `sqlComment` every accessor shares, for the batch paths that bypass them. */
+    private get sqlCommenter();
     private readonly errorMessagesSafe;
     /**
      * THIS client's error-message mode. Not the process default: see
@@ -732,6 +1030,10 @@ export declare class TurbineClient {
     private readonly ownsPool;
     /** Active LISTEN subscriptions, torn down on disconnect() so it never hangs */
     private readonly activeSubscriptions;
+    /** `$on('poolError')` / `$on('connectionLost')` listeners. */
+    private readonly poolListeners;
+    /** What each pool Turbine opened has checked out, for `disconnect({ timeoutMs })`. */
+    private readonly checkoutWatches;
     /**
      * Read-replica pools in round-robin order. Empty when no replicas are
      * configured, in which case `table()` takes the original single-pool path.
@@ -778,8 +1080,10 @@ export declare class TurbineClient {
     private static resolveTemporalInfinity;
     private static resolvePlanCacheMode;
     /**
-     * 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
@@ -813,7 +1117,50 @@ export declare class TurbineClient {
      * should set the GUC on the server or role instead
      * (`ALTER ROLE ... SET plan_cache_mode = ...`).
      */
-    private static withPlanCacheMode;
+    private static ownedPoolConfig;
+    /**
+     * Validate `statementTimeoutMs`: a non-negative integer (E003), on
+     * PostgreSQL only (E017), since it is applied as a PostgreSQL connection
+     * parameter.
+     */
+    private static resolveStatementTimeout;
+    /**
+     * 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`.
+     */
+    private static poolerEndpoint;
+    /** Always on: named statements behind a transaction pooler fail in production first. */
+    private static warnPreparedOnPooler;
+    /**
+     * `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.
+     */
+    private typedPool;
+    /**
+     * 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.
+     */
+    private watchOwnedPool;
+    /**
+     * 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.
+     */
+    private emitPoolEvent;
+    /**
+     * `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.
+     */
+    private warnExternalPoolOptions;
     /**
      * Refuse a `utcTimestamps` value that contradicts the one an earlier client
      * in this process settled the zone-less temporal read parsers (OIDs 1114,
@@ -886,8 +1233,22 @@ export declare class TurbineClient {
      * ```
      */
     $use(middleware: Middleware): void;
-    $on(_event: 'query', listener: QueryEventListener): void;
-    $off(_event: 'query', listener: QueryEventListener): void;
+    /**
+     * Subscribe to client events:
+     *   - `'query'`: one {@link QueryEvent} per statement.
+     *   - `'poolError'`: an idle pooled connection failed ({@link PoolErrorEvent}).
+     *   - `'connectionLost'`: a checked-out connection failed ({@link ConnectionLostEvent}).
+     *
+     * Pool events come from the pools this client opened; an external `pool`
+     * emits its own. Any other event name throws `ValidationError` (E003).
+     */
+    $on(event: 'query', listener: QueryEventListener): void;
+    $on(event: 'poolError', listener: (event: PoolErrorEvent) => void): void;
+    $on(event: 'connectionLost', listener: (event: ConnectionLostEvent) => void): void;
+    $off(event: 'query', listener: QueryEventListener): void;
+    $off(event: 'poolError', listener: (event: PoolErrorEvent) => void): void;
+    $off(event: 'connectionLost', listener: (event: ConnectionLostEvent) => void): void;
+    private listenersFor;
     private observeEngine?;
     $observe(config: ObserveConfig): Promise<ObserveHandle>;
     /**
@@ -987,7 +1348,13 @@ export declare class TurbineClient {
      * extended-query pipeline protocol (one TCP flush, one round-trip).
      * On HTTP-based drivers it falls back to sequential execution.
      */
-    pipeline<T extends readonly DeferredQuery<unknown>[]>(...args: T | [T, PipelineOptions?]): Promise<PipelineResults<T>>;
+    pipeline<T extends readonly DeferredQuery<unknown>[]>(...queries: T): Promise<PipelineResults<T>>;
+    pipeline<T extends readonly DeferredQuery<unknown>[]>(queries: readonly [...T], options?: PipelineOptions): Promise<PipelineResults<T>>;
+    /**
+     * 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.
+     */
+    private statementComments;
     /**
      * {@link pipeline} with one `$on('query')` event per statement. Only taken
      * when a listener is registered, so an unobserved pipeline runs exactly as
@@ -1006,6 +1373,10 @@ export declare class TurbineClient {
     pipelineSupported(): Promise<boolean>;
     /**
      * 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
@@ -1017,6 +1388,26 @@ export declare class TurbineClient {
      * ```
      */
     raw<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    /**
+     * 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);
+     * ```
+     */
+    rawUnsafe<T extends Record<string, unknown> = Record<string, unknown>>(text: string, ...values: unknown[]): Promise<T[]>;
+    private runRaw;
     /**
      * @internal The `turbine-orm/prisma-compat` adapter's pool-level raw seam,
      * the twin of {@link TransactionClient.rawQuery}. NOT application API: use
@@ -1030,6 +1421,12 @@ export declare class TurbineClient {
         rows: T[];
         rowCount: number | null;
     }>;
+    /**
+     * 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.
+     */
+    private rawParams;
     /**
      * 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
@@ -1086,10 +1483,16 @@ export declare 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
@@ -1142,13 +1545,50 @@ export declare class TurbineClient {
      * ]);
      * ```
      */
-    $transaction<T extends readonly DeferredQuery<unknown>[]>(queries: readonly [...T]): Promise<PipelineResults<T>>;
+    $transaction<T extends readonly DeferredQuery<unknown>[]>(queries: readonly [...T], options?: TransactionOptions): Promise<PipelineResults<T>>;
     private runTransaction;
     /**
-     * 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`.
+     * 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.
+     */
+    private resolveTransactionOptions;
+    /**
+     * 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.
+     */
+    private runInTransaction;
+    /**
+     * 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'`.
+     */
+    private resolveSessionContext;
+    /**
+     * 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
@@ -1169,7 +1609,7 @@ export declare 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.
      */
-    private transactionBatch;
+    private runBatch;
     /**
      * Convenience wrapper around `$transaction` for the multi-tenant / RLS case:
      * runs `fn` inside a transaction with the given session GUCs applied via
@@ -1212,7 +1652,8 @@ export declare 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
@@ -1262,15 +1703,47 @@ export declare class TurbineClient {
      * Throws if the connection fails.
      */
     connect(): Promise<void>;
+    /**
+     * 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.
+     */
+    $ping(): Promise<number>;
+    /**
+     * `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).
+     */
+    private roundTrip;
     /**
      * 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.
+     * Waits for every checked-out connection to be returned, then closes them
+     * all. With `timeoutMs`, it stops waiting at the deadline: each connection
+     * still in use has its running statement cancelled on the server and is
+     * closed (a transaction on it rolls back), and the result says how many
+     * were. Resolves within about `timeoutMs` plus two seconds of grace.
+     *
+     * If Turbine was given an external pool via `TurbineConfig.pool`, the
+     * primary is left open, the caller is responsible for its lifecycle;
+     * Turbine-owned replica pools are still closed.
      */
     disconnect(): Promise<void>;
+    disconnect(options: DisconnectOptions): Promise<DisconnectResult>;
+    /**
+     * 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.
+     */
+    private forceCloseCheckedOut;
     /** Alias for disconnect() */
     end(): Promise<void>;
+    end(options: DisconnectOptions): Promise<DisconnectResult>;
     /**
      * Pool statistics for monitoring. Returns zeros for pools that don't
      * expose connection counts (e.g., stateless HTTP drivers like Neon).