turbine-orm 0.70.0 → 0.71.0

package/dist/cjs/cli/mcp.js

@@ -17,6 +17,7 @@ const introspect_js_1 = require("../introspect.js");
 const index_js_1 = require("../query/index.js");
 const utils_js_1 = require("../query/utils.js");
 const schema_js_1 = require("../schema.js");
+const compile_query_js_1 = require("./compile-query.js");
 const error_catalog_js_1 = require("./error-catalog.js");
 const migrate_js_1 = require("./migrate.js");
 const pii_predicate_guard_js_1 = require("./pii-predicate-guard.js");
@@ -170,6 +171,27 @@ const TOOLS = [
             additionalProperties: false,
         },
     },
+    {
+        name: 'compile_query',
+        description: 'Compile a Turbine read query to the EXACT SQL it would send, WITHOUT running it: no statement is executed and no row is read, so this is safe to call on production and safe to call in a loop. Use it before you write the query into code. Pass `table`, an `operation` (findMany / findUnique / findFirst / count / aggregate / groupBy, default findMany) and `args`, the same object you would pass to that method. Returns the SQL, the bound parameters, how many STATEMENTS the query costs at execution (a `with` clause can be one join or one follow-up per relation), which relation-load strategy it takes, whether it is bounded by a LIMIT or reads the whole table, the relation depth, and warnings such as a relation whose correlation column has no index. A query that FAILS to compile is a successful answer, not an error: an unknown column (TURBINE_E003), an unknown relation (TURBINE_E005) or the empty-where guard comes back as `ok: false` with the code, the message and how to fix it. READ OPERATIONS ONLY, deliberately: this server has no write surface and compiling one would be the first. A where or orderBy on a PII-tagged or secret-named column is refused, exactly as in explain_query.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string', description: 'Table name (must exist in the introspected schema).' },
+                operation: {
+                    type: 'string',
+                    enum: [...compile_query_js_1.COMPILE_OPERATIONS],
+                    description: 'Which read method to compile. Defaults to findMany.',
+                },
+                args: {
+                    type: 'object',
+                    description: 'The query args, exactly as the method takes them: where / orderBy / with / select / omit / limit / offset / take / cursor / distinct / relationLoadStrategy for the find methods, and by / having / _count / _sum / _avg / _min / _max for aggregate and groupBy. Field and relation names are validated against the live schema.',
+                },
+            },
+            required: ['table'],
+            additionalProperties: false,
+        },
+    },
     {
         name: 'sample_rows',
         description: 'Read up to 50 rows from a validated table. PII-tagged and secret-named columns are never fetched; the reply lists exactly what was hidden and where the PII tags came from.',
@@ -396,6 +418,9 @@ async function callTool(params, ctx) {
         case 'explain_query':
             result = await explainQuery(ctx, args);
             break;
+        case 'compile_query':
+            result = await compileQuery(ctx, args);
+            break;
         case 'sample_rows':
             result = await sampleRows(ctx, requiredString(args, 'table'), optionalLimit(args.limit));
             break;
@@ -749,6 +774,27 @@ async function explainQuery(ctx, args) {
  * column can be shown to be safe, so every where/orderBy is refused rather than
  * assumed harmless.
  */
+/**
+ * Why this column may not appear in a predicate, or null when it may.
+ *
+ * The two reasons are the two `sample_rows` already refuses to FETCH
+ * (`classifyHiddenColumns`), and they are deliberately the same set: a column
+ * whose bytes are too sensitive to sample is too sensitive to binary-search out
+ * of the planner. A column absent from the table is not judged here, the builder
+ * rejects it by name a moment later.
+ *
+ * ONE definition, shared by `explain_query` and `compile_query`. It was inline
+ * in the former, and lifting it out is the same move that made the WALK shared:
+ * two tools that hide different sets of columns are two perimeters, and the
+ * weaker one is the one an attacker uses.
+ */
+function hiddenColumnReason(owner, column) {
+    if (owner.columns.some((col) => col.name === column && col.pii === true))
+        return 'is PII-tagged';
+    if (SECRET_NAME_PATTERN.test(column))
+        return 'has a secret-looking name';
+    return null;
+}
 function assertNoPiiPredicates(args, table, metadata, piiTags) {
     const hasPredicate = args.where !== undefined || args.orderBy !== undefined;
     if (tagsUnreadable(piiTags) && hasPredicate) {
@@ -758,22 +804,7 @@ function assertNoPiiPredicates(args, table, metadata, piiTags) {
     }
     (0, pii_predicate_guard_js_1.assertNoPiiPredicates)(args, table, {
         metadata,
-        /**
-         * Why this column may not appear in a predicate, or null when it may.
-         *
-         * The two reasons are the two `sample_rows` already refuses to FETCH
-         * (`classifyHiddenColumns`), and they are deliberately the same set: a
-         * column whose bytes are too sensitive to sample is too sensitive to
-         * binary-search out of the planner. A column absent from the table is not
-         * judged here, the builder rejects it by name a moment later.
-         */
-        hiddenReason: (owner, column) => {
-            if (owner.columns.some((col) => col.name === column && col.pii === true))
-                return 'is PII-tagged';
-            if (SECRET_NAME_PATTERN.test(column))
-                return 'has a secret-looking name';
-            return null;
-        },
+        hiddenReason: hiddenColumnReason,
         refuseColumn: (owner, column, why) => {
             throw jsonRpcError(-32602, `Column "${column}" on "${owner.name}" ${why}, so it cannot be used in a where or orderBy here: ` +
                 `EXPLAIN reports the planner's row estimate, and the estimate for a predicate on a hidden value ` +
@@ -790,6 +821,157 @@ function assertNoPiiPredicates(args, table, metadata, piiTags) {
         },
     });
 }
+// ---------------------------------------------------------------------------
+// compile_query, the build half of the ORM with the execute half removed
+// ---------------------------------------------------------------------------
+/**
+ * Compile a read query to SQL and describe it, WITHOUT running it.
+ *
+ * WHAT THIS TOOL DOES AND DOES NOT TOUCH. It reads the CATALOG, once, in its
+ * own `BEGIN READ ONLY` transaction, because it cannot validate a column name
+ * against a schema it has not seen. That read finishes and the connection goes
+ * back to the pool BEFORE anything is compiled: the compile itself is handed
+ * `SEALED_POOL` (see `cli/compile-query.ts`), whose every method throws, so the
+ * compiled statement has no live connection to escape down and the "compiles,
+ * never executes" claim is a property of the code rather than of this comment.
+ * That split is also why the compile is not inside `withReadOnly`: a build walk
+ * on a deep `with` clause has no business holding one of a max:2 pool's
+ * connections while an agent waits.
+ *
+ * WHY THE PII GUARD RUNS HERE AT ALL, given this tool returns no row and no row
+ * ESTIMATE, and so is not the extraction oracle `explain_query` is. Two
+ * reasons, and the first is the load-bearing one. A tool that will compile
+ * `WHERE "api_key" LIKE $1` is a tool that authors the probe for the agent to
+ * run somewhere this server does not control; refusing to write it keeps one
+ * rule ("do not build queries that interrogate a hidden value") rather than two
+ * that differ by which tool you asked. And second, an unguarded compile is a
+ * cheap way to discover which SPELLINGS of a predicate against a hidden column
+ * the builder accepts, which is reconnaissance for the tool that does leak. The
+ * guard is the same shared walker, with the same `hiddenColumnReason` policy
+ * `explain_query` uses, so the two cannot drift apart.
+ */
+async function compileQuery(ctx, args) {
+    // Same explicit rejection explain_query makes: an agent that reaches for a
+    // raw-SQL argument should be told the surface does not exist, not told that
+    // `table` is missing.
+    if ('sql' in args) {
+        throw jsonRpcError(-32602, 'compile_query never accepts SQL; it PRODUCES it. Pass table + operation + args (the object you would ' +
+            'hand to findMany / findUnique / findFirst / count / aggregate / groupBy).');
+    }
+    const tableName = requiredString(args, 'table');
+    const operation = parseCompileOperation(args.operation);
+    const queryArgs = parseCompileArgs(args.args);
+    const { metadata, piiTags } = await withReadOnly(ctx, (client) => loadSchemaMetadata(client, ctx.options));
+    const table = requireTable(metadata, tableName);
+    assertCompileHidesNothing(queryArgs, operation, table, metadata, piiTags);
+    let report;
+    try {
+        report = (0, compile_query_js_1.compileQueryPlan)({ metadata, table, operation, args: queryArgs });
+    }
+    catch (err) {
+        // Not a TurbineError (compileQueryPlan turns those into an `ok: false`
+        // answer): a malformed args shape the builder rejected some other way.
+        throw jsonRpcError(-32602, errorMessage(err));
+    }
+    return {
+        schema: ctx.options.schema,
+        ...report,
+        executed: false,
+        executedNote: 'Nothing was executed. This tool compiles the statement and returns it; the only database access it makes ' +
+            'is the read-only catalog read that resolves table, column and relation names.',
+    };
+}
+/** The requested operation, defaulted to findMany and checked against the closed set. */
+function parseCompileOperation(value) {
+    if (value === undefined || value === null)
+        return 'findMany';
+    if (typeof value !== 'string' || !compile_query_js_1.COMPILE_OPERATIONS.includes(value)) {
+        throw jsonRpcError(-32602, `operation must be one of ${compile_query_js_1.COMPILE_OPERATIONS.join(', ')}. Write operations are not compiled by this ` +
+            'server: it has no write surface at all, which is stronger than having one that refuses to run.');
+    }
+    return value;
+}
+/**
+ * The query args, passed through whole.
+ *
+ * Deliberately NOT an allowlist of keys the way `parseExplainFindManyArgs` is.
+ * The point of this tool is that the agent compiles the object it is about to
+ * paste into its code, so a key this parser dropped would compile a DIFFERENT
+ * query than the one that ships, silently, which is worse than any error. Every
+ * key is therefore judged by the two things that already judge them correctly:
+ * the PII guard, which fails closed on a shape it does not recognize, and the
+ * builder, which throws E003 by name for an unknown one. The two privilege
+ * options that would matter (`includePii`, `skipGlobalFilters`) are unlocked by
+ * a symbol sentinel that `JSON.parse` cannot produce, so neither is reachable
+ * over this wire.
+ */
+function parseCompileArgs(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (!isObject(value))
+        throw jsonRpcError(-32602, 'args must be an object');
+    return value;
+}
+/**
+ * Refuse a compile that names a hidden column anywhere it could name one.
+ *
+ * TWO WALKS, because the arg surface has two shapes. The findMany-shaped ops go
+ * through the shared `cli/pii-predicate-guard.ts` walker exactly as
+ * `explain_query` does, relation-aware and fail-closed. `aggregate` / `groupBy`
+ * hand it their `where` only, and everything else through
+ * `collectAggregateColumnNames`: the shared walker's `visitLevel` fails closed
+ * on any object-valued key outside its findMany vocabulary, so handing it a
+ * `by` array or a `_min` block would refuse EVERY aggregate rather than check
+ * one, and teaching it those shapes means a second module that has to stay in
+ * step with the aggregate compiler. The harvest is blunter and errs the safe
+ * way; see its own doc comment.
+ */
+function assertCompileHidesNothing(args, operation, table, metadata, piiTags) {
+    if (tagsUnreadable(piiTags) && (0, compile_query_js_1.carriesColumnNamingArg)(args)) {
+        throw jsonRpcError(-32602, `PII tags could not be read from ${piiTags.path} (${piiTags.reason}), so compile_query cannot prove this ` +
+            `query does not filter, sort or group on a PII column. Re-run \`turbine generate\`, or compile the query ` +
+            `without where/orderBy/cursor/distinct/by/having and the aggregate blocks.`);
+    }
+    const aggregateShaped = (0, compile_query_js_1.isAggregateShaped)(operation);
+    const predicateArgs = aggregateShaped ? { where: args.where } : args;
+    (0, pii_predicate_guard_js_1.assertNoPiiPredicates)(predicateArgs, table, {
+        metadata,
+        hiddenReason: hiddenColumnReason,
+        refuseColumn: (owner, column, why) => {
+            throw jsonRpcError(-32602, `Column "${column}" on "${owner.name}" ${why}, so compile_query will not build a statement that filters, ` +
+                `sorts, pages or groups on it. This server does not author queries that interrogate a hidden value, ` +
+                `wherever that statement would eventually run. Use a visible column.`);
+        },
+        refuseDepth: (maxDepth) => {
+            throw jsonRpcError(-32602, `Query is nested more than ${maxDepth} levels deep, past the point where the PII guard can prove it does ` +
+                `not name a hidden column, so it is refused. Flatten the query.`);
+        },
+        refuseShape: (owner, key) => {
+            throw jsonRpcError(-32602, `The PII guard does not recognize "${key}" in a query on "${owner.name}", so it cannot prove the query ` +
+                `does not name a hidden column, and refuses it rather than guessing. Remove it and compile without it.`);
+        },
+    });
+    if (!aggregateShaped)
+        return;
+    let names;
+    try {
+        names = (0, compile_query_js_1.collectAggregateColumnNames)(args);
+    }
+    catch (err) {
+        // The harvest throws only on its depth cap, which is the same fail-closed
+        // posture the shared walker takes, reported the same way.
+        throw jsonRpcError(-32602, errorMessage(err));
+    }
+    for (const name of names) {
+        const column = (0, utils_js_1.ownLookup)(table.columnMap, name) ?? name;
+        const why = hiddenColumnReason(table, column);
+        if (!why)
+            continue;
+        throw jsonRpcError(-32602, `Column "${column}" on "${table.name}" ${why}, so it cannot be used as a group key, an aggregate target, a ` +
+            `HAVING term or an ordering in compile_query. _count over the table is unaffected; group and aggregate on ` +
+            `a visible column instead.`);
+    }
+}
 /**
  * Extract the allowed findMany subset for explain_query (no `with` / raw SQL).
  * Returns a plain object cast at the buildFindMany call site, same pattern as Studio.

package/dist/cjs/client.d.ts

@@ -26,7 +26,7 @@ import { type ErrorMessageMode } from './errors.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 QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy, type TemporalInfinityReading } from './query/index.js';
+import { type DeferredQuery, type GlobalFilters, type JsonEncoding, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy, type TemporalInfinityReading } from './query/index.js';
 import { type NotificationHandler, type Subscription } from './realtime.js';
 import type { SchemaMetadata } from './schema.js';
 import { TypedSqlQuery } from './typed-sql.js';
@@ -367,19 +367,31 @@ export interface TurbineConfig {
     /**
      * How nested-relation subqueries encode each row's JSON.
      *
-     *   - `'object'` (default), `json_agg(json_build_object('key', v, …))`. Every
-     *     key name is repeated in every nested object of every row.
+     *   - `'object'`, `json_agg(json_build_object('key', v, …))`. Every key name
+     *     is repeated in every nested object of every row.
      *   - `'positional'`, `json_agg(json_build_array(v, …))`. Turbine knows the
      *     column order at build time, so it emits a key-less array and maps
      *     positions back to keys client-side. Same information, a fraction of the
-     *     bytes on wide/deeply-nested `with` trees. Parsed output is byte-identical
-     *     to `'object'`.
-     *
-     * Postgres-only in v1: setting `'positional'` on a non-Postgres engine throws
-     * `UnsupportedFeatureError` (E017) when a `with` clause is present. Default:
-     * `'object'` (today's behavior, byte-unchanged).
+     *     bytes on wide/deeply-nested `with` trees. Parsed output is
+     *     byte-identical to `'object'`.
+     *
+     * DEFAULTS BY ENGINE: `'positional'` on PostgreSQL, `'object'` on SQLite,
+     * MySQL, SQL Server and PowDB. Positional is PostgreSQL-only, and setting it
+     * on another engine throws `UnsupportedFeatureError` (E017) as soon as a
+     * `with` clause is present, so the default cannot be one value everywhere.
+     *
+     * Why positional is the PostgreSQL default. `json_build_object` makes the
+     * SERVER build the key names for every relation row, which is the whole
+     * nested-read cost: measured on a 50-parent / ~10-child-per-parent read
+     * against local PostgreSQL 17, server time 0.685 ms → 0.350 ms and 152 KB →
+     * 100 KB on the wire, for rows that compare byte-identical.
+     *
+     * Reasons to set `'object'` (per query via `findMany({ jsonEncoding })`, or
+     * here for a whole client): a readable statement in a query log, and
+     * `relationLoadStrategy: 'flatten'`, which is refused while positional is
+     * active because a flattened relation emits no JSON to encode.
      */
-    jsonEncoding?: 'object' | 'positional';
+    jsonEncoding?: JsonEncoding;
     /**
      * Controls how `NotFoundError` (and other where-aware errors) format their
      * messages.
@@ -532,6 +544,24 @@ export interface TransactionOptions {
      */
     sessionContext?: Record<string, string | number | boolean>;
 }
+/**
+ * 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).
+ */
+/**
+ * Operations that may be served by a read replica.
+ *
+ * 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.
+ *
+ * Exported for that test only.
+ */
+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.
@@ -781,6 +811,11 @@ export declare class TurbineClient {
      * query-string boundary: a connection string with an unencoded `?` inside the
      * password is not parseable by pg either, so there is no shape this handles
      * differently from the driver.
+     *
+     * A twin of this lives in `src/connection-url.ts`, which `turbine doctor`
+     * uses for `statement_timeout`. Unifying them is the obvious refactor and it
+     * is deliberately NOT done; the reason (a c8 merge artifact that costs almost
+     * all of the coverage gate's headroom) is written up over there.
      */
     private static mergeConnectionStringOptions;
     /**

package/dist/cjs/client.js

@@ -26,7 +26,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TurbineClient = exports.TransactionClient = void 0;
+exports.TurbineClient = exports.TransactionClient = exports.READ_OPERATIONS = void 0;
 exports.withRetry = withRetry;
 const pg_1 = __importDefault(require("pg"));
 const dialect_js_1 = require("./dialect.js");
@@ -414,7 +414,19 @@ const GUC_NAME_REGEX = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
  * 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).
  */
-const READ_OPERATIONS = new Set([
+/**
+ * Operations that may be served by a read replica.
+ *
+ * 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.
+ *
+ * Exported for that test only.
+ */
+exports.READ_OPERATIONS = new Set([
     'findMany',
     'findFirst',
     'findUnique',
@@ -424,6 +436,7 @@ const READ_OPERATIONS = new Set([
     'aggregate',
     'groupBy',
     'findManyStream',
+    'findManyStreamBatches',
 ]);
 /**
  * Internal marker on the config object that tells the `TurbineClient`
@@ -1154,6 +1167,11 @@ class TurbineClient {
      * query-string boundary: a connection string with an unencoded `?` inside the
      * password is not parseable by pg either, so there is no shape this handles
      * differently from the driver.
+     *
+     * A twin of this lives in `src/connection-url.ts`, which `turbine doctor`
+     * uses for `statement_timeout`. Unifying them is the obvious refactor and it
+     * is deliberately NOT done; the reason (a c8 merge artifact that costs almost
+     * all of the coverage gate's headroom) is written up over there.
      */
     static mergeConnectionStringOptions(connectionString, setting) {
         const q = connectionString.indexOf('?');
@@ -1442,7 +1460,7 @@ class TurbineClient {
         const client = this;
         return new Proxy(primaryQI, {
             get(target, prop, receiver) {
-                if (typeof prop === 'string' && READ_OPERATIONS.has(prop)) {
+                if (typeof prop === 'string' && exports.READ_OPERATIONS.has(prop)) {
                     // Pick the replica at CALL time so round-robin advances per operation.
                     return (...args) => {
                         const replicaQI = client.nextReplicaTableQI(name);

package/dist/cjs/connection-url.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Connection-string inspection: pooler detection, and connection-time GUCs.
+ *
+ * A pure leaf. It imports nothing (not even `pg`), so every consumer, the CLI,
+ * the statistics collectors, and the tests, reads the same rules without
+ * dragging a driver in.
+ *
+ * ## Why this file exists
+ *
+ * A **transaction-pooling** proxy (PgBouncer, a Neon `-pooler` endpoint,
+ * Supabase's pooler) does not give a client its own server backend. It
+ * multiplexes many clients onto a few shared backends and hands a backend back
+ * to the pool at the end of each TRANSACTION, without running `DISCARD ALL`.
+ * Two consequences drive everything below:
+ *
+ *   1. A session-level `SET` issued outside an explicit transaction attaches to
+ *      whichever shared backend served that statement, and stays there for the
+ *      next client that gets it. A `SET statement_timeout` meant to bound one
+ *      tool's own reads becomes a setting imposed on an application's queries.
+ *      This is a production-incident class, not a theoretical one.
+ *   2. Session-scoped catalogs (`pg_prepared_statements` above all) describe
+ *      whichever backend answered, which through a pooler is not "your" session
+ *      in any useful sense.
+ *
+ * So there are two jobs here. {@link withStatementTimeoutOption} removes the
+ * need for the `SET` in (1) by moving the GUC into the connection's startup
+ * parameters, the same mechanism `TurbineClient` uses for `plan_cache_mode`.
+ * {@link detectPooler} lets a command that depends on session semantics refuse
+ * the endpoint outright rather than degrade silently.
+ *
+ * NEITHER is a substitute for the other. The connection parameter is what makes
+ * the collectors safe for any caller; the refusal is what keeps a diagnostic
+ * command from reporting confidently about a connection it cannot reason about.
+ */
+/** Host and port pulled out of a connection string, `null` when not stated. */
+export interface ConnectionTarget {
+    /** Lower-cased hostname, or `null` for a unix socket / unparseable string. */
+    host: string | null;
+    /** Port number, or `null` when the string does not name one. */
+    port: number | null;
+}
+/**
+ * Host and port from a connection string, in either shape libpq accepts.
+ *
+ * URL form (`postgres://user:pw@host:5432/db`) goes through `URL`; the
+ * key/value DSN form (`host=db.example.com port=6543 dbname=app`) falls back to
+ * a scan. An unparseable string yields `{ host: null, port: null }`, which every
+ * caller here treats as "no evidence", never as "safe".
+ */
+export declare function parseConnectionTarget(connectionString: string): ConnectionTarget;
+/**
+ * Hostname tokens that name a pooler.
+ *
+ * Matched as whole dot/dash/underscore-delimited TOKENS (with an optional
+ * trailing instance number), never as substrings of the connection string.
+ * Substring matching is what makes this class of check untrustworthy: a
+ * database named `poolers`, a role named `pooler_admin`, or a host called
+ * `spooler.internal` all contain the letters and none of them is a pooler, and
+ * a detector that cries wolf gets disabled by the first person it blocks.
+ */
+export declare const POOLER_HOST_TOKENS: readonly string[];
+/**
+ * Ports that name a pooler on their own.
+ *
+ * 6543 is the transaction-pooling port of the hosted poolers people point a CLI
+ * at. 6432 is PgBouncer's own documented default `listen_port`, so anyone who
+ * ran PgBouncer without changing it is here.
+ *
+ * The counter-argument to 6432 is that it refuses someone running plain
+ * Postgres on a non-standard port. That is true and it is the right trade,
+ * because the two errors do not cost the same: a false positive costs one
+ * `--allow-pooler` flag on a command the user is running interactively and
+ * reading the output of, while a false negative is silently the exact hazard
+ * this gate exists to prevent. When a detector's errors are asymmetric, tune it
+ * toward the cheap one.
+ */
+export declare const POOLER_PORTS: readonly number[];
+/** Which rule fired, for a message that can say exactly what it saw. */
+export type PoolerSignal = 'host' | 'port';
+export interface PoolerDetection {
+    /** True when the connection string looks like a transaction-pooling endpoint. */
+    pooled: boolean;
+    /** The rule that fired, or `null` when nothing did. */
+    signal: PoolerSignal | null;
+    host: string | null;
+    port: number | null;
+    /** The token that matched, for a `host` signal. */
+    matchedToken: string | null;
+    /**
+     * The direct hostname, when it is DERIVABLE rather than guessed: only the
+     * in-label `-pooler` / `-pgbouncer` suffix form (Neon's
+     * `ep-x-pooler.<region>.aws.neon.tech`) yields one. When the token is a whole
+     * label the direct endpoint is a different name entirely (Supabase's pooler
+     * is `<region>.pooler.supabase.com` while its direct host is
+     * `db.<ref>.supabase.co`), so this stays `null` rather than inventing a
+     * hostname that does not resolve.
+     */
+    directHost: string | null;
+}
+/**
+ * Whether a connection string points at a transaction-pooling proxy.
+ *
+ * Deliberately conservative: it answers from the endpoint's SHAPE (hostname
+ * tokens, port), because there is no way to ask a pooler what it is without
+ * connecting through it, and the whole point is to decide before connecting.
+ * A false negative leaves the caller where it already was; a false positive
+ * blocks a legitimate database, so precision wins and the caller is expected to
+ * offer an override.
+ */
+export declare function detectPooler(connectionString: string): PoolerDetection;
+export interface PoolerRefusalOptions {
+    /** The command being refused, e.g. `turbine doctor`. */
+    command: string;
+    /** The flag that overrides the refusal, e.g. `--allow-pooler`. */
+    allowFlag: string;
+}
+/**
+ * The lines a command prints when it refuses a pooler endpoint.
+ *
+ * Plain text, no colour and no `console` call, so it is assertable in a unit
+ * test and reusable by any command that grows the same gate.
+ */
+export declare function poolerRefusalMessage(detection: PoolerDetection, options: PoolerRefusalOptions): string[];
+/** A pg pool/client config, narrowed to the two fields this helper touches. */
+export interface ConnectionOptionsConfig {
+    connectionString: string;
+    /** libpq `options` startup parameter. */
+    options?: string;
+}
+/**
+ * `config` with `statement_timeout` moved into the connection's **startup
+ * parameters** (`options=-c statement_timeout=<ms>`) instead of a `SET`.
+ *
+ * PostgreSQL applies the `options` startup parameter as the backend starts the
+ * session, so the bound is in force for the connection's very first statement
+ * and for its whole life, with no extra round trip and nothing to reset. The
+ * alternative, `SET statement_timeout = <ms>` on a fresh connection, is what
+ * this exists to remove: outside an explicit transaction it is exactly the
+ * session-state write that a transaction pooler leaves on a shared backend.
+ *
+ * `TurbineClient` uses the same mechanism for `plan_cache_mode`; see the note
+ * there for why a `pool.on('connect')` `SET` is not the alternative it looks
+ * like (it races the caller's first query through pg's deprecated same-client
+ * queueing).
+ *
+ * Nothing already set is discarded, in either place pg reads `options` from.
+ * pg's `ConnectionParameters` lets a value parsed out of the connection string
+ * OVERRIDE the explicit `options` field, so when the URL already carries
+ * `?options=...` the GUC is appended THERE; the explicit field itself falls back
+ * to `process.env.PGOPTIONS` only while unset, so setting it blind would drop a
+ * deployment's `PGOPTIONS`. Both are read first and appended to.
+ *
+ * THE INJECTION BOUNDARY: a GUC value cannot be a bind parameter, so the
+ * emitted text necessarily contains a literal. `statementTimeoutMs` is
+ * therefore narrowed to a non-negative safe INTEGER and rendered from the
+ * narrowed number; anything else (a float, a negative, `NaN`, a string that
+ * coerced) returns the config untouched rather than reaching the wire, because
+ * a value that can carry a space can carry a second `-c`.
+ */
+export declare function withStatementTimeoutOption(config: ConnectionOptionsConfig, statementTimeoutMs: number): ConnectionOptionsConfig;