turbine-orm 0.70.0 → 0.71.0

package/dist/cjs/cli/compile-query.js

@@ -0,0 +1,529 @@
+"use strict";
+/**
+ * turbine-orm CLI: compile a read query WITHOUT executing it.
+ *
+ * Turbine already separates BUILD from EXECUTE: every `build*()` method on
+ * `QueryInterface` returns a {@link DeferredQuery} (`{ sql, params, transform,
+ * tag }`) and nothing runs until something calls `execute()`. This module is
+ * that seam turned into a tool: hand it schema metadata and a set of `findMany`
+ * -shaped args, get back the exact statement the ORM would send, the bound
+ * parameter list, and a read of whether the query is a mistake.
+ *
+ * ZERO DATABASE ACCESS, ENFORCED BY CONSTRUCTION RATHER THAN BY REVIEW.
+ * `QueryInterface` takes a pool in its constructor and never touches it on the
+ * build path, so this module hands it {@link SEALED_POOL}, whose every method
+ * THROWS. That is the whole guarantee: a future build path that grew a query
+ * would fail loudly here instead of quietly opening a connection, and the
+ * "compiles nothing, runs nothing" claim in the tool description does not
+ * depend on anyone re-reading the builder. The caller is responsible for
+ * obtaining `SchemaMetadata`; this module reads no catalog of its own.
+ *
+ * WHAT IT REFUSES TO DO. Read operations only, and that is a property of this
+ * module, not of its caller: {@link COMPILE_OPERATIONS} is the closed set, and
+ * a name outside it never reaches a builder. A write's SQL text is arguably as
+ * harmless to display as a read's, but the TOOL SURFACE is the security
+ * boundary on an agent-facing server, and "we also compile deletes, we just
+ * don't run them" is an argument, where "there is no write path" is a fact.
+ *
+ * A COMPILE FAILURE IS AN ANSWER, NOT AN ERROR. `where: { titel: 'x' }` throws
+ * `ValidationError` (E003) and `with: { autor: true }` throws `RelationError`
+ * (E005); both are exactly what the caller asked to find out, one round trip
+ * before the code is written. So a `TurbineError` out of the builder comes back
+ * as a successful result carrying the code, the message, the docs URL and the
+ * catalog's causes/fixes. Anything that is NOT a TurbineError propagates: it is
+ * a bug or a malformed request, and dressing it up as a query verdict would
+ * hide it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COLUMN_NAMING_ARG_KEYS = exports.SEALED_POOL = exports.COMPILE_OPERATIONS = void 0;
+exports.isAggregateShaped = isAggregateShaped;
+exports.carriesColumnNamingArg = carriesColumnNamingArg;
+exports.compileQueryPlan = compileQueryPlan;
+exports.collectAggregateColumnNames = collectAggregateColumnNames;
+const errors_js_1 = require("../errors.js");
+const index_advisor_js_1 = require("../index-advisor.js");
+const index_js_1 = require("../query/index.js");
+const utils_js_1 = require("../query/utils.js");
+const error_catalog_js_1 = require("./error-catalog.js");
+const pii_predicate_guard_js_1 = require("./pii-predicate-guard.js");
+/**
+ * The read operations this module compiles. A CLOSED set, checked before any
+ * builder is reached, which is what keeps the read-only stance a fact rather
+ * than a convention: there is no branch here that reaches `buildCreate`,
+ * `buildUpdate`, `buildDelete` or `buildUpsert`.
+ */
+exports.COMPILE_OPERATIONS = ['findMany', 'findUnique', 'findFirst', 'count', 'aggregate', 'groupBy'];
+/** True for the two operations whose args are NOT findMany-shaped. */
+function isAggregateShaped(operation) {
+    return operation === 'aggregate' || operation === 'groupBy';
+}
+/**
+ * A pool that refuses every call.
+ *
+ * `QueryInterface`'s constructor requires one, and the build path never uses
+ * it. Passing a sealed object rather than the caller's real pool is what makes
+ * "this compiles and does not execute" structurally true: there is no live
+ * connection in scope for a statement to escape down, and a future build path
+ * that tried to read something would throw a message naming this file rather
+ * than silently issuing a query on an agent's behalf.
+ */
+exports.SEALED_POOL = {
+    query() {
+        throw new Error('[turbine] compile-query: the compile path must never execute a statement (sealed pool)');
+    },
+    connect() {
+        throw new Error('[turbine] compile-query: the compile path must never open a connection (sealed pool)');
+    },
+    end() {
+        throw new Error('[turbine] compile-query: the compile path owns no connection to close (sealed pool)');
+    },
+};
+/**
+ * Serialized length past which a bound parameter is summarized instead of
+ * echoed. A TOKEN budget, not a security boundary: see the params note in
+ * {@link compileQueryPlan}.
+ */
+const PARAM_ECHO_MAX_CHARS = 200;
+/** Depth past which the with-clause walk stops describing relations. */
+const WITH_WALK_MAX_DEPTH = 12;
+/**
+ * Query-arg keys that name a column or an ordering over one, in any of the six
+ * operations. Used only by the caller's fail-closed check for an unreadable PII
+ * tag scan: with no trustworthy tag list, a compile carrying any of these
+ * cannot be shown not to name a hidden column.
+ *
+ * `select` / `omit` / `with` are deliberately absent, matching the guard's own
+ * rule: they return values, and this tool returns no values at all.
+ */
+exports.COLUMN_NAMING_ARG_KEYS = [
+    'where',
+    'orderBy',
+    'cursor',
+    'distinct',
+    'by',
+    'having',
+    'distinctOn',
+    '_count',
+    '_sum',
+    '_avg',
+    '_min',
+    '_max',
+];
+/** Does this args object carry a key that names a column? */
+function carriesColumnNamingArg(args) {
+    return exports.COLUMN_NAMING_ARG_KEYS.some((key) => args[key] !== undefined);
+}
+// ---------------------------------------------------------------------------
+// Compile
+// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** A where clause that actually constrains something. `{}` compiles to no WHERE. */
+function hasRealWhere(args) {
+    const where = args.where;
+    if (!isPlainObject(where))
+        return false;
+    return Object.values(where).some((value) => value !== undefined);
+}
+function positiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : null;
+}
+/**
+ * Compile one read query and describe it. Never touches a database; see the
+ * module header for why that is enforced rather than promised.
+ */
+function compileQueryPlan(input) {
+    const { metadata, table, operation, args } = input;
+    // THIS OPTIONS LITERAL IS WHAT MAKES `paramNote` TRUE. Every element of
+    // `deferred.params` traces back to a value the caller wrote in `args`, and it
+    // does so because exactly two core features bind a value the caller did not
+    // write: a configured `globalFilters` entry, and `defaultLimit`. Neither is
+    // set here. Adding either to this literal turns the echoed parameter list into
+    // a disclosure channel for the application's own configuration, so do not,
+    // and if a third such feature ever lands, it belongs on this list rather than
+    // in the reply.
+    const qi = new index_js_1.QueryInterface(exports.SEALED_POOL, table.name, metadata, [], {
+        // Diagnostics come from this module, not from a console warning fired into
+        // the operator's stderr on someone else's behalf.
+        warnOnUnlimited: false,
+        // The cache is per-QueryInterface and this one is discarded with the reply,
+        // so leaving it ON would only ever miss. It stays OFF for the same reason
+        // `explain_query` and Studio's builder turn it off: a diagnostic compile
+        // must not be able to seed or read a shared template. The prepared-statement
+        // NAME is unaffected, `buildCacheEntry` computes it either way, which is
+        // what lets the report tell a named shape from an unnamed one.
+        sqlCache: false,
+        preparedStatements: false,
+    });
+    let deferred;
+    try {
+        deferred = compileOne(qi, operation, args);
+    }
+    catch (err) {
+        if (err instanceof errors_js_1.TurbineError) {
+            return { ok: false, table: table.name, operation, error: describeTurbineError(err) };
+        }
+        throw err;
+    }
+    const requested = args.relationLoadStrategy ?? null;
+    const effective = requested ?? input.clientRelationLoadStrategy ?? 'auto';
+    const relations = [];
+    let relationsTruncated = false;
+    if (isPlainObject(args.with)) {
+        relationsTruncated = walkWith(metadata, table, args.with, 1, '', relations);
+    }
+    const relationDepth = relations.reduce((max, relation) => Math.max(max, relation.depth), 0);
+    const params = deferred.params.map(echoParam);
+    const paramsTruncated = params.some((entry) => entry.truncated);
+    const named = deferred.preparedName !== '' && deferred.preparedName !== undefined;
+    const bound = describeBound(operation, args);
+    const hasWhere = hasRealWhere(args);
+    const success = {
+        table: table.name,
+        operation,
+        sql: deferred.sql,
+        params: params.map((entry) => entry.value),
+        paramCount: deferred.params.length,
+        paramsTruncated,
+        paramNote: 'Every bound value here came from this request. The compiler binds no value of its own on this path: ' +
+            'the two core features that would (a configured global filter, and a client-level default limit) are not ' +
+            'enabled on the compiling interface. A value whose serialized form exceeds ' +
+            `${PARAM_ECHO_MAX_CHARS} characters is summarized rather than echoed, and paramsTruncated says so.`,
+        preparedStatement: {
+            named,
+            name: named ? (deferred.preparedName ?? null) : null,
+            note: named
+                ? 'This shape executes as a NAMED prepared statement, so the server parses and plans it once per ' +
+                    'connection and reuses it.'
+                : 'This shape executes UNNAMED. Two things give a statement up its server-side name, and this query has ' +
+                    'at least one: a caller-written AND / OR ARRAY in the where or having clause (whose LENGTH is written ' +
+                    'into the SQL text, one parenthesized branch per element), or a MULTI-column `distinct` (whose column ' +
+                    'list is written in one term at a time, so the reachable statement set is the ordered subsets of the ' +
+                    'table). Either way a list assembled from variable input would mint statements the server never ' +
+                    'deallocates, so unnamed is the bound. It costs one re-parse per execution and changes no SQL. Use ' +
+                    '`in: [...]` where you can: it binds one array parameter whatever the list length.',
+        },
+        statements: describeStatements(operation, effective, relations.length, args),
+        plan: {
+            relationLoadStrategy: { requested, effective, note: strategyNote(requested, effective, relations.length) },
+            relationCount: relations.length,
+            relationDepth,
+            relations,
+            relationsTruncated,
+            hasWhere,
+            hasOrderBy: args.orderBy !== undefined,
+            bounded: bound.bounded,
+            limit: bound.limit,
+            boundedBy: bound.by,
+            readsEveryRow: !hasWhere,
+        },
+        advice: buildAdvice(operation, relations, relationDepth, named, hasWhere, bound),
+        note: 'This is the statement the ORM would send. It was compiled and NOT executed: no connection was opened and ' +
+            'no query ran, so the numbers here are properties of the query, never of your data.',
+    };
+    return { ok: true, ...success };
+}
+/** Dispatch to the one builder for this operation. The only place operations map to builders. */
+function compileOne(qi, operation, args) {
+    switch (operation) {
+        case 'findMany':
+            return qi.buildFindMany(args);
+        // `as unknown as` for the two arg types with a REQUIRED member
+        // (`findUnique.where`, `groupBy.by`). Omitting it is a caller error the
+        // builder raises as a typed `ValidationError`, which is the answer this tool
+        // exists to hand back, so the cast must not pre-empt it with a TypeScript
+        // complaint about args that arrived over JSON-RPC anyway.
+        case 'findUnique':
+            return qi.buildFindUnique(args);
+        case 'findFirst':
+            return qi.buildFindFirst(args);
+        case 'count':
+            return qi.buildCount(args);
+        case 'aggregate':
+            return qi.buildAggregate(args);
+        case 'groupBy':
+            return qi.buildGroupBy(args);
+    }
+}
+/**
+ * A thrown `TurbineError`, as the caller's answer.
+ *
+ * The catalog fields are folded in here rather than left to the caller because
+ * this is the one place that knows a compile FAILED, and an agent holding
+ * `TURBINE_E003` with no idea what E003 means is one tool call away from
+ * guessing. Absent when the code is not catalogued (nothing here invents one).
+ */
+function describeTurbineError(err) {
+    const explanation = (0, error_catalog_js_1.explainErrorCode)(err.code);
+    return {
+        code: err.code,
+        message: err.message,
+        docsUrl: err.docsUrl,
+        className: explanation?.className,
+        whenThrown: explanation?.whenThrown,
+        likelyCauses: explanation?.likelyCauses,
+        howToFix: explanation?.howToFix,
+    };
+}
+/**
+ * One bound parameter, sized for an LLM context.
+ *
+ * A withholding is LABELLED, never expressed by dropping the value: an absent
+ * element would renumber the list and make `$3` in the SQL point at the wrong
+ * entry, which is a worse answer than a marker.
+ */
+function echoParam(value) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        return { value: '(value withheld: not JSON-serializable)', truncated: true };
+    }
+    if (json === undefined)
+        return { value: null, truncated: false };
+    if (json.length <= PARAM_ECHO_MAX_CHARS)
+        return { value, truncated: false };
+    if (typeof value === 'string') {
+        return { value: `${value.slice(0, PARAM_ECHO_MAX_CHARS)}… (truncated, ${value.length} chars)`, truncated: true };
+    }
+    return { value: `(value withheld: ${json.length} serialized chars, too large to echo)`, truncated: true };
+}
+/**
+ * Describe every relation the `with` clause reaches.
+ *
+ * Runs only AFTER a successful compile, so an unknown relation name cannot
+ * appear here: the builder has already refused it as E005. Returns true when
+ * the walk stopped at {@link WITH_WALK_MAX_DEPTH}, which is reported rather
+ * than silently swallowed.
+ */
+function walkWith(metadata, table, withClause, depth, prefix, out) {
+    if (depth > WITH_WALK_MAX_DEPTH)
+        return true;
+    let truncated = false;
+    for (const [key, spec] of Object.entries(withClause)) {
+        // `_count` is an inline aggregate, not a relation node: it adds no follow-up
+        // statement and has no target table of its own.
+        if (key === '_count')
+            continue;
+        const relation = (0, utils_js_1.ownLookup)(table.relations, key);
+        if (!relation)
+            continue;
+        const path = prefix ? `${prefix}.${relation.name}` : relation.name;
+        out.push({
+            path,
+            name: relation.name,
+            type: relation.type,
+            from: relation.from,
+            to: relation.to,
+            depth,
+            returnsArray: relation.type === 'hasMany' || relation.type === 'manyToMany',
+            limit: isPlainObject(spec) ? positiveInteger(spec.limit) : null,
+            unindexedProbe: (0, index_advisor_js_1.missingIndexForRelation)(metadata, relation),
+        });
+        const target = (0, utils_js_1.ownLookup)(metadata.tables, relation.to);
+        if (target && isPlainObject(spec) && isPlainObject(spec.with)) {
+            truncated = walkWith(metadata, target, spec.with, depth + 1, path, out) || truncated;
+        }
+    }
+    return truncated;
+}
+/** Whether the query is bounded to a known number of rows, and by what. */
+function describeBound(operation, args) {
+    if (operation === 'findUnique')
+        return { bounded: true, limit: 1, by: 'findUnique (a unique where matches one row)' };
+    if (operation === 'findFirst')
+        return { bounded: true, limit: 1, by: 'findFirst (LIMIT 1)' };
+    if (operation === 'count' || operation === 'aggregate') {
+        return { bounded: true, limit: 1, by: `${operation} (one result row)` };
+    }
+    // `by` names the key that actually produced the number, not merely the key
+    // that was present: `{ limit: 0, take: 5 }` is bounded BY TAKE.
+    const fromLimit = positiveInteger(args.limit);
+    if (fromLimit !== null)
+        return { bounded: true, limit: fromLimit, by: 'limit' };
+    const fromTake = positiveInteger(args.take);
+    if (fromTake !== null)
+        return { bounded: true, limit: fromTake, by: 'take' };
+    return { bounded: false, limit: null, by: null };
+}
+/**
+ * How many statements this query costs at execution.
+ *
+ * Only two of the four strategies have a knowable answer before the query runs,
+ * and saying so is the point: `'auto'` decides its split per relation at
+ * execute time from index coverage and the parent-row bound, so a number here
+ * would be a guess dressed as a fact. It gets a RANGE and a reason instead.
+ */
+function describeStatements(operation, effective, relationCount, args) {
+    if (!isPlainObject(args.with) || relationCount === 0) {
+        return { compiled: 1, atExecution: 1, note: 'No relations to load, so this is a single statement.' };
+    }
+    if (operation === 'count' || operation === 'aggregate' || operation === 'groupBy') {
+        return {
+            compiled: 1,
+            atExecution: 1,
+            note: `A ${operation} loads no relations, so a \`with\` clause here does not add statements.`,
+        };
+    }
+    if (effective === 'batched') {
+        return {
+            compiled: 1,
+            atExecution: 1 + relationCount,
+            note: `The base statement plus one flat follow-up per relation (${relationCount}), stitched client-side. A ` +
+                'parent set with more than 32,000 correlation keys is chunked, which adds a statement per chunk.',
+        };
+    }
+    if (effective === 'auto') {
+        return {
+            compiled: 1,
+            atExecution: null,
+            note: `Between 1 and ${1 + relationCount}. \`auto\` plans the single-statement join and falls back to a batched ` +
+                'follow-up PER RELATION whose correlation column is provably unindexed, or whose parent set is unbounded; ' +
+                'that decision is made at execute time, so it is not knowable here. The SQL above is the join plan. Pass ' +
+                "relationLoadStrategy: 'join' or 'batched' to compile a query whose statement count is fixed.",
+        };
+    }
+    return {
+        compiled: 1,
+        atExecution: 1,
+        note: effective === 'flatten'
+            ? 'One statement: eligible to-one relations compile to a LEFT JOIN, and any relation that is not eligible ' +
+                'silently falls back to a correlated subquery in the same statement.'
+            : 'One statement: every relation is a correlated json_agg subquery inside the SELECT above.',
+    };
+}
+function strategyNote(requested, effective, relationCount) {
+    if (relationCount === 0)
+        return 'This query loads no relations, so the relation-load strategy does not apply.';
+    if (requested !== null)
+        return `The query asked for '${requested}', so that is what it compiles to.`;
+    return `The query names no strategy, so it inherits the client default ('${effective}').`;
+}
+/**
+ * The part that answers "is this query a mistake" rather than "what SQL is it".
+ *
+ * Every entry is derived from the compiled query or from schema metadata, never
+ * from data, so nothing here can be wrong because a table is empty today.
+ */
+function buildAdvice(operation, relations, relationDepth, named, hasWhere, bound) {
+    const advice = [];
+    if (operation === 'findMany' && !bound.bounded) {
+        advice.push({
+            code: 'unbounded-read',
+            severity: 'warn',
+            message: hasWhere
+                ? 'This findMany has no `limit`, so it returns every row matching the filter. That set grows with the ' +
+                    'table; add a `limit` (and an `orderBy` so the page is deterministic).'
+                : 'This findMany has neither a `where` nor a `limit`, so it reads and returns the whole table. Add a ' +
+                    'filter, a limit, or both.',
+        });
+    }
+    // `findUnique` is excluded because the builder refuses one with no predicate
+    // (E003), so it can never reach this point without a where.
+    if (!hasWhere && operation !== 'findUnique') {
+        advice.push({
+            code: 'no-filter',
+            severity: 'info',
+            message: 'No `where` clause, so the engine has no predicate to use an index for and must consider every row of ' +
+                'the table. A LIMIT bounds the rows RETURNED, not the rows scanned.',
+        });
+    }
+    for (const relation of relations) {
+        if (!relation.unindexedProbe)
+            continue;
+        advice.push({
+            code: 'unindexed-relation-probe',
+            severity: 'warn',
+            message: `Relation "${relation.path}" probes ${relation.unindexedProbe.table}(${relation.unindexedProbe.columns.join(', ')}), ` +
+                'which no index serves. Under the single-statement join that probe is a full scan re-run once per parent ' +
+                `row. Create the index (${relation.unindexedProbe.createSql}) or load this relation batched.`,
+        });
+    }
+    if (relationDepth > 5) {
+        advice.push({
+            code: 'deep-with',
+            severity: 'warn',
+            message: `The \`with\` clause is ${relationDepth} levels deep. Under the join strategy each level is a correlated ` +
+                'subquery the engine re-evaluates once per row of the level above, so the work multiplies down the tree. ' +
+                'Split the query, or load it batched.',
+        });
+    }
+    const unlimitedToMany = relations.filter((relation) => relation.returnsArray && relation.limit === null);
+    if (unlimitedToMany.length > 0) {
+        advice.push({
+            code: 'unbounded-relation',
+            severity: 'info',
+            message: `To-many relation(s) ${unlimitedToMany.map((relation) => relation.path).join(', ')} carry no per-relation ` +
+                '`limit`, so every child row of every parent is materialized into the result. Set a `limit` on the ' +
+                'relation if you only need the first few.',
+        });
+    }
+    if (!named) {
+        advice.push({
+            code: 'unnamed-prepared-statement',
+            severity: 'info',
+            message: 'This shape executes as an UNNAMED prepared statement, because a caller-written AND / OR array or a ' +
+                'multi-column `distinct` writes its own LENGTH into the SQL text. That is deliberate and bounds server ' +
+                'memory; the cost is one re-parse per execution. Prefer `in: [...]` for a variable-length list.',
+        });
+    }
+    return advice;
+}
+// ---------------------------------------------------------------------------
+// Aggregate-shaped column names, for the caller's PII guard
+// ---------------------------------------------------------------------------
+/**
+ * Every string that could be a column name anywhere in an `aggregate` /
+ * `groupBy` args object, EXCLUDING `where` (which the shared PII predicate
+ * guard walks properly).
+ *
+ * DELIBERATELY BLUNTER THAN THE SHARED WALKER, and blunt in the fail-closed
+ * direction. The aggregate arg surface names columns in positions the where /
+ * orderBy walker was never built for: `by` names them as ARRAY ELEMENTS,
+ * `_min` / `_max` / `_sum` / `_avg` as KEYS one level under an aggregate block,
+ * `having` as keys under both, and a JSON-path group key names one inside a
+ * `{ field, path }` object. Teaching the shared walker each of those shapes
+ * means a second place that has to stay in step with the aggregate compiler,
+ * which is the exact failure mode `cli/pii-predicate-guard.ts` exists to end.
+ *
+ * So this harvests EVERY string in key or value position and hands the lot to
+ * the caller's column resolver. A string that is not a column resolves to
+ * nothing and is ignored; a string that IS a hidden column is refused wherever
+ * it appears. The cost is a false refusal on a schema whose hidden column is
+ * named `desc` or `_all`; the benefit is that a new aggregate arg shape is
+ * covered the day it ships, with no edit here.
+ *
+ * `where` is excluded because the shared walker already covers it with the
+ * relation-aware precision this cannot have.
+ */
+function collectAggregateColumnNames(args) {
+    const names = new Set();
+    const visit = (value, depth) => {
+        if (depth > pii_predicate_guard_js_1.PII_GUARD_MAX_DEPTH) {
+            throw new RangeError(`[turbine] compile-query: aggregate args are nested more than ${pii_predicate_guard_js_1.PII_GUARD_MAX_DEPTH} levels deep`);
+        }
+        if (typeof value === 'string') {
+            names.add(value);
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, depth + 1);
+            return;
+        }
+        if (!isPlainObject(value))
+            return;
+        for (const [key, member] of Object.entries(value)) {
+            names.add(key);
+            visit(member, depth + 1);
+        }
+    };
+    for (const [key, value] of Object.entries(args)) {
+        if (key === 'where')
+            continue;
+        visit(value, 1);
+    }
+    return [...names];
+}

package/dist/cjs/cli/index.d.ts

@@ -14,7 +14,7 @@
  *   turbine migrate status       , Show migration status
  *   turbine seed                 , Run seed file
  *   turbine status               , Show schema summary
- *   turbine doctor                - Index + cached-plan triage (--fix, --json, --no-concurrently, --unused, --audit, --no-plan-divergence)
+ *   turbine doctor                - Index + cached-plan triage (--fix, --json, --no-concurrently, --unused, --audit, --no-plan-divergence, --allow-pooler)
  *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                  , Start read-only MCP server over JSON-RPC stdio
  *   turbine observe              , Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
@@ -63,6 +63,8 @@ export interface CliArgs {
     metricsUrl?: string;
     /** `doctor --no-plan-divergence`: skip the cached-plan divergence section (and its pg_stats read). */
     noPlanDivergence?: boolean;
+    /** `doctor --allow-pooler`: run even when the connection string looks like a transaction pooler. */
+    allowPooler?: boolean;
     /** `init --yes`/`-y`: accept every step's default non-interactively. */
     yes?: boolean;
     /** `init --skip-schema`: don't scaffold the schema file. */
@@ -454,6 +456,28 @@ export type SeedExecutionPlan = {
     file: string;
 };
 export declare function getSeedExecutionPlan(seedFile: string): SeedExecutionPlan;
+/**
+ * Refuse a `doctor` run whose connection string points at a transaction pooler.
+ *
+ * Called BEFORE anything opens a connection, which is the whole point: the
+ * refusal has to happen while the only thing anybody has touched is a string.
+ *
+ * Doctor is a diagnostic command that reads statistics and reasons about
+ * cached plans, and both of those arguments assume the session it is talking to
+ * is its own. Through a pooler it is not: session state this process sets can be
+ * left on a shared backend for someone else's queries, and the session-scoped
+ * view the report's own remediation tells the reader to inspect
+ * (`pg_prepared_statements`) belongs to whichever backend happened to answer.
+ * Refusing is the honest outcome; reporting confidently over a connection whose
+ * session semantics do not hold is not.
+ *
+ * Written to STDERR, including in `--json` mode, where stdout is contracted to
+ * carry the report and nothing else.
+ *
+ * Exported for the unit test only (like {@link isLoopbackHost}): a gate whose
+ * failure path is `process.exit` is untestable through the command itself.
+ */
+export declare function refusePoolerConnection(url: string, args: CliArgs): void;
 /**
  * True when `host` is a loopback address Studio/Observe may bind without
  * `--allow-remote`. Accepts IPv4, IPv6, and the common bracket form.

package/dist/cjs/cli/index.js

@@ -15,7 +15,7 @@
  *   turbine migrate status       , Show migration status
  *   turbine seed                 , Run seed file
  *   turbine status               , Show schema summary
- *   turbine doctor                - Index + cached-plan triage (--fix, --json, --no-concurrently, --unused, --audit, --no-plan-divergence)
+ *   turbine doctor                - Index + cached-plan triage (--fix, --json, --no-concurrently, --unused, --audit, --no-plan-divergence, --allow-pooler)
  *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                  , Start read-only MCP server over JSON-RPC stdio
  *   turbine observe              , Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
@@ -77,12 +77,14 @@ exports.resolveMigrateFromPrismaUrl = resolveMigrateFromPrismaUrl;
 exports.readPrismaSchemaSource = readPrismaSchemaSource;
 exports.buildMigrateDeployOptions = buildMigrateDeployOptions;
 exports.getSeedExecutionPlan = getSeedExecutionPlan;
+exports.refusePoolerConnection = refusePoolerConnection;
 exports.isLoopbackHost = isLoopbackHost;
 exports.showSubcommandHelp = showSubcommandHelp;
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_url_1 = require("node:url");
+const connection_url_js_1 = require("../connection-url.js");
 const generate_js_1 = require("../generate.js");
 const index_advisor_js_1 = require("../index-advisor.js");
 const index_stats_js_1 = require("../index-stats.js");
@@ -222,6 +224,9 @@ function parseArgs(argv = process.argv.slice(2)) {
             case '--no-plan-divergence':
                 result.noPlanDivergence = true;
                 break;
+            case '--allow-pooler':
+                result.allowPooler = true;
+                break;
             case '--zod':
                 result.zod = true;
                 break;
@@ -2674,9 +2679,46 @@ const CONCURRENTLY_RECIPE_COMMENT = [
     '--      makes "migrate up" look hung. For bounded waits, SET lock_timeout /',
     '--      statement_timeout in a psql session.',
 ].join('\n');
+/**
+ * Refuse a `doctor` run whose connection string points at a transaction pooler.
+ *
+ * Called BEFORE anything opens a connection, which is the whole point: the
+ * refusal has to happen while the only thing anybody has touched is a string.
+ *
+ * Doctor is a diagnostic command that reads statistics and reasons about
+ * cached plans, and both of those arguments assume the session it is talking to
+ * is its own. Through a pooler it is not: session state this process sets can be
+ * left on a shared backend for someone else's queries, and the session-scoped
+ * view the report's own remediation tells the reader to inspect
+ * (`pg_prepared_statements`) belongs to whichever backend happened to answer.
+ * Refusing is the honest outcome; reporting confidently over a connection whose
+ * session semantics do not hold is not.
+ *
+ * Written to STDERR, including in `--json` mode, where stdout is contracted to
+ * carry the report and nothing else.
+ *
+ * Exported for the unit test only (like {@link isLoopbackHost}): a gate whose
+ * failure path is `process.exit` is untestable through the command itself.
+ */
+function refusePoolerConnection(url, args) {
+    if (args.allowPooler === true)
+        return;
+    const detection = (0, connection_url_js_1.detectPooler)(url);
+    if (!detection.pooled)
+        return;
+    const lines = (0, connection_url_js_1.poolerRefusalMessage)(detection, { command: 'turbine doctor', allowFlag: '--allow-pooler' });
+    console.error('');
+    console.error(`  ${(0, ui_js_1.red)(ui_js_1.symbols.cross)} ${lines[0]}`);
+    for (const line of lines.slice(1))
+        console.error(line === '' ? '' : `  ${line}`);
+    console.error('');
+    process.exit(1);
+}
 async function cmdDoctor(args, config) {
     const jsonMode = args.json === true;
     const url = requireUrl(config);
+    // Before the banner, before introspect, before any pool is constructed.
+    refusePoolerConnection(url, args);
     if (!jsonMode) {
         (0, ui_js_1.banner)();
         (0, ui_js_1.label)('Database', (0, ui_js_1.redactUrl)(url));
@@ -3862,6 +3904,12 @@ function showDoctorHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--min-scans')} ${(0, ui_js_1.dim)('<n>')}       idx_scan below this counts as never-scanned ${(0, ui_js_1.dim)('(default: 1)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--metrics-url')} ${(0, ui_js_1.dim)('<url>')}   Read ${(0, ui_js_1.cyan)('_turbine_metrics')} for the table-heat boost from a separate DB`);
     console.log(`    ${(0, ui_js_1.cyan)('--no-plan-divergence')}  Skip the cached-plan divergence section ${(0, ui_js_1.dim)('(and its pg_stats read)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-pooler')}        Run against a connection pooler anyway ${(0, ui_js_1.dim)('(refused by default)')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.dim)('doctor refuses a transaction-pooling endpoint (a')} ${(0, ui_js_1.cyan)('-pooler')} ${(0, ui_js_1.dim)('or')} ${(0, ui_js_1.cyan)('pgbouncer')}`);
+    console.log(`  ${(0, ui_js_1.dim)('host, or port 6543). Point it at the direct endpoint instead: a pooler')}`);
+    console.log(`  ${(0, ui_js_1.dim)('shares one server backend between clients, so neither the session state')}`);
+    console.log(`  ${(0, ui_js_1.dim)('doctor needs nor the session-scoped views it cites belong to it.')}`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine doctor`);