turbine-orm 0.33.0 → 0.35.0

package/dist/cjs/query/builder.js

@@ -177,6 +177,11 @@ class QueryInterface {
     warnOnUnlimited;
     utcTimestamps;
     preparedStatementsEnabled;
+    /**
+     * Whether the SQL template cache is active. Set once in the constructor.
+     * Mutable (not `readonly`) only so {@link withSqlCacheDisabled} can flip it
+     * off around a single synchronous compile (see {@link explain}).
+     */
     sqlCacheEnabled;
     dialect;
     /** Client-level default relation-loading strategy ('join' unless configured). */
@@ -870,6 +875,61 @@ class QueryInterface {
             return deferred.transform(result);
         });
     }
+    /**
+     * Return the engine's query plan for a {@link findMany}-shaped query as plain
+     * text lines: a diagnostic surface for inspecting how the database will run a
+     * query (index usage, join strategy, scan type).
+     *
+     * The compiled SELECT is prefixed with the dialect's explain syntax
+     * (Postgres `EXPLAIN`, SQLite `EXPLAIN QUERY PLAN`, MySQL `EXPLAIN
+     * FORMAT=TREE`) and run as a read. The findMany args are compiled with the
+     * SQL template cache disabled, so an explain never reads or writes the shared
+     * cache. Middleware is NOT applied: the returned rows are plan text, not
+     * entity rows. Each result row is flattened to one line by joining its column
+     * values with a single space (Postgres returns one `QUERY PLAN` text column,
+     * SQLite's `EXPLAIN QUERY PLAN` returns four, MySQL's tree format one).
+     *
+     * Only `findMany` shapes are supported (where / orderBy / with / limit /
+     * pagination). Engines whose plan cannot be requested in-band from a compiled
+     * query (SQL Server, whose SHOWPLAN is a session toggle) throw
+     * {@link UnsupportedFeatureError} (E017).
+     *
+     * The plan text itself is engine-owned and NOT covered by semver: its content
+     * and formatting can change with the underlying database version.
+     */
+    async explain(args) {
+        const explainSyntax = this.dialect.explainQuery;
+        if (!explainSyntax) {
+            throw new errors_js_1.UnsupportedFeatureError('explain()', this.dialect.name, 'This engine cannot explain a compiled query in-band.');
+        }
+        // Compile the findMany SQL with the cache disabled: the prefixed EXPLAIN
+        // statement is a one-off diagnostic and must never read or write the shared
+        // query-template cache.
+        const deferred = this.withSqlCacheDisabled(() => this.buildFindMany(args));
+        const sql = `${explainSyntax.prefix} ${deferred.sql}`;
+        this.currentAction = 'explain';
+        // No preparedName: keep the diagnostic statement out of the prepared path.
+        const result = await this.queryWithTimeout(sql, deferred.params, args?.timeout);
+        return result.rows.map((row) => Object.values(row)
+            .map((value) => (typeof value === 'string' ? value : String(value)))
+            .join(' '));
+    }
+    /**
+     * Run `fn` with the SQL template cache forced off, restoring the prior state
+     * afterward. Used by {@link explain}, whose one-off prefixed statement must
+     * neither read nor write the shared cache. `fn` is synchronous, so no query
+     * interleaves between the toggle and its restore.
+     */
+    withSqlCacheDisabled(fn) {
+        const prev = this.sqlCacheEnabled;
+        this.sqlCacheEnabled = false;
+        try {
+            return fn();
+        }
+        finally {
+            this.sqlCacheEnabled = prev;
+        }
+    }
     /**
      * Emit a one-time `console.warn` when {@link findMany} is called without an
      * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.
@@ -4527,7 +4587,18 @@ class QueryInterface {
         const extract = this.dialect.buildJsonPathExtract(`${prefix}${this.q(col)}`, this.p(params.length));
         const lhs = spec.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
         const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-        return `${lhs} ${dir}${this.nullsSuffix(spec.nulls)}`;
+        // Rows whose document lacks the path extract to NULL. Without a nulls
+        // clause, Postgres DESC defaults to NULLS FIRST, which both diverges from
+        // pick-row ordering (NULLS LAST both directions since 0.33) and from
+        // engines whose path ordering is nulls-last in both directions. Default to
+        // NULLS LAST in BOTH directions unless the caller set `nulls` explicitly;
+        // the grammar gate matches nullsSuffix.
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        return `${lhs} ${dir}${nullsSql}`;
     }
     /**
      * Compile a relation ordering term. For a to-many relation the only allowed

package/dist/cjs/schema-builder.js

@@ -25,6 +25,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.camelToSnake = exports.column = exports.ColumnBuilder = void 0;
+exports.isDocFieldIndexDef = isDocFieldIndexDef;
 exports.defineSchema = defineSchema;
 exports.table = table;
 exports.applyManyToManyRelations = applyManyToManyRelations;
@@ -102,6 +103,10 @@ function resolveColumn(def) {
         check: def.check ?? null,
     };
 }
+/** Type guard: is this index declaration a doc-field expression index? */
+function isDocFieldIndexDef(idx) {
+    return 'docField' in idx && typeof idx.docField === 'string';
+}
 /** Check if a value is a TableDef (from legacy table() builder) */
 function isTableDef(v) {
     return typeof v === 'object' && v !== null && 'columns' in v && 'name' in v;
@@ -145,7 +150,17 @@ function defineSchema(input, options) {
             let pk;
             let m2m;
             let checks;
+            let indexes;
             for (const [fieldName, def] of Object.entries(raw)) {
+                if (fieldName === 'indexes') {
+                    if (def !== undefined) {
+                        if (!Array.isArray(def)) {
+                            throw new Error(`Table "${accessor}": "indexes" must be an array of index declarations`);
+                        }
+                        indexes = def;
+                    }
+                    continue;
+                }
                 if (fieldName === 'manyToMany') {
                     if (def !== undefined) {
                         if (!Array.isArray(def)) {
@@ -205,6 +220,7 @@ function defineSchema(input, options) {
                 ...(pk && pk.length > 0 ? { primaryKey: pk } : {}),
                 ...(m2m && m2m.length > 0 ? { manyToMany: m2m } : {}),
                 ...(checks && checks.length > 0 ? { checks } : {}),
+                ...(indexes && indexes.length > 0 ? { indexes } : {}),
             };
         }
     }

package/dist/cjs/schema-metadata.js

@@ -25,10 +25,12 @@
  *     the same conservative auto-`manyToMany` treatment as introspection.
  *   - Explicit `manyToMany` declarations on the SchemaDef are merged via
  *     {@link applyManyToManyRelations} (additive, never clobbering).
- *   - `indexes` is always `[]` — SchemaDef cannot express indexes, and an
- *     empty list keeps `schemaHasIndexInfo()` false so the index advisor
- *     and the dev-mode missing-index warning stay silent instead of
- *     producing blanket false positives.
+ *   - `indexes` carries any declared `TableDef.indexes` (plain column and/or
+ *     PowDB doc-field expression indexes); a table with none declared gets
+ *     `[]`, which keeps `schemaHasIndexInfo()` false so the index advisor and
+ *     the dev-mode missing-index warning stay silent instead of producing
+ *     blanket false positives. Doc-field (docPath) indexes are ignored by the
+ *     advisor, so a doc-only index set never flips `schemaHasIndexInfo()`.
  *
  * @example
  * ```ts
@@ -45,6 +47,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.schemaDefToMetadata = schemaDefToMetadata;
+const errors_js_1 = require("./errors.js");
 const introspect_js_1 = require("./introspect.js");
 const schema_js_1 = require("./schema.js");
 const schema_builder_js_1 = require("./schema-builder.js");
@@ -97,6 +100,67 @@ function resolveColumnName(raw, target) {
     return (0, schema_js_1.camelToSnake)(raw);
 }
 // ---------------------------------------------------------------------------
+// Index declarations → IndexMetadata
+// ---------------------------------------------------------------------------
+/**
+ * Render a doc-field JSON path into an illustrative PowQL fragment for the
+ * `IndexMetadata.definition` field (debuggability only; the authoritative,
+ * lexer-exact emission lives in `powqlSchemaDDL`). String segments are shown
+ * double-quoted, integer array indexes bare.
+ */
+function docPathFragment(column, path) {
+    const segs = path.map((s) => (typeof s === 'number' ? `->${s}` : `->"${s}"`)).join('');
+    return `(.${column}${segs})`;
+}
+/**
+ * Convert a table's {@link SchemaIndexDef} list into {@link IndexMetadata}.
+ * A doc-field index carries `docPath` and `columns: [<json column>]`; a plain
+ * column index carries its snake_case column list and no `docPath`. Names are
+ * auto-derived (`<table>_<cols>_idx`) when not supplied.
+ */
+function mapIndexes(tableDef, declared) {
+    if (!declared || declared.length === 0)
+        return [];
+    const out = [];
+    for (const idx of declared) {
+        if ((0, schema_builder_js_1.isDocFieldIndexDef)(idx)) {
+            const column = (0, schema_js_1.camelToSnake)(idx.docField);
+            const segPart = idx.path.map((s) => (typeof s === 'number' ? String(s) : s)).join('_');
+            const name = idx.name ?? `${tableDef.name}_${column}_${segPart}_idx`;
+            // Validate numeric (array-index) segments up front: PowDB rejects a
+            // negative / fractional / NaN JSON-path index at migration time with an
+            // opaque parse error, so fail here with a typed ValidationError naming the
+            // index instead of emitting malformed PowQL later.
+            for (const seg of idx.path) {
+                if (typeof seg === 'number' && (!Number.isInteger(seg) || seg < 0)) {
+                    throw new errors_js_1.ValidationError(`[turbine] Doc-field index "${name}" on "${tableDef.name}": array-index path segment ${seg} must be a ` +
+                        'non-negative integer (a JSON array index). Use a string for an object key.');
+                }
+            }
+            out.push({
+                name,
+                columns: [column],
+                unique: idx.unique ?? false,
+                definition: `${idx.unique ? 'unique ' : 'index '}${docPathFragment(column, idx.path)}`,
+                docPath: [...idx.path],
+                declared: true,
+            });
+        }
+        else {
+            const columns = idx.columns.map(schema_js_1.camelToSnake);
+            const name = idx.name ?? `${tableDef.name}_${columns.join('_')}_idx`;
+            out.push({
+                name,
+                columns,
+                unique: idx.unique ?? false,
+                definition: `${idx.unique ? 'unique ' : 'index '}(${columns.join(', ')})`,
+                declared: true,
+            });
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
 // The converter
 // ---------------------------------------------------------------------------
 /**
@@ -122,10 +186,14 @@ function resolveColumnName(raw, target) {
  *   - Explicit `manyToMany` declarations → merged additively.
  *   - Schema-level `enums`.
  *
+ * What maps (continued):
+ *   - `indexes` → declared `TableDef.indexes` become `IndexMetadata` (plain
+ *     column indexes and PowDB doc-field expression indexes, the latter
+ *     carrying `docPath`). A table with no declared indexes gets `[]`, keeping
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no false
+ *     positives on index-less code-first metadata.
+ *
  * What SchemaDef cannot express (and how it degrades):
- *   - Indexes → every table gets `indexes: []`, which keeps
- *     `schemaHasIndexInfo()` false so index-advisor consumers produce no
- *     false positives on code-first metadata.
  *   - Views → never marked (`isView` is introspection-only).
  *   - Composite foreign keys → `references:` is single-column by design.
  */
@@ -302,9 +370,12 @@ function schemaDefToMetadata(def) {
             primaryKey: pk,
             uniqueColumns,
             relations: relationsByTable.get(tableDef.name) ?? {},
-            // SchemaDef cannot express indexes. An empty list keeps
-            // schemaHasIndexInfo() false → no index-advisor false positives.
-            indexes: [],
+            // Declared `indexes` (plain column + doc-field expression) carry through;
+            // an undeclared table gets `[]`, which keeps schemaHasIndexInfo() false so
+            // the index advisor stays silent. Doc-field (docPath) indexes are ignored
+            // by the advisor entirely (see index-advisor.ts), so a doc-only index set
+            // never flips schemaHasIndexInfo() and never produces FK false positives.
+            indexes: mapIndexes(tableDef, tableDef.indexes),
         };
     }
     const enums = {};

package/dist/cjs/sqlite.js

@@ -380,6 +380,9 @@ exports.sqliteDialect = {
     supportsAdvisoryLock: false,
     // No FROM-clause LATERAL: the opt-in lateral pick plan is Postgres-only.
     supportsLateralJoin: false,
+    // SQLite explains a compiled query with `EXPLAIN QUERY PLAN` (four columns:
+    // id, parent, notused, detail), overriding the inherited Postgres `EXPLAIN`.
+    explainQuery: { prefix: 'EXPLAIN QUERY PLAN' },
     // json_group_array / json_object have no inline ORDER BY argument, so every
     // ordered to-many relation is forced through the inner-subquery rewrite.
     aggSupportsInlineOrderBy: false,

package/dist/client.d.ts

@@ -181,13 +181,17 @@ export interface TurbineConfig {
      * Default strategy for resolving `with`-clause relations, applied to every
      * `findMany`/`findUnique`/`findFirst` unless overridden per query.
      *
-     *   - `'join'` (default) — one SQL statement using correlated
-     *     `json_agg(json_build_object(...))` subqueries.
-     *   - `'batched'` — run the base query, then one flat follow-up query per
+     *   - `'join'`: one SQL statement using correlated
+     *     `json_agg(json_build_object(...))` subqueries. On PowDB, `'join'` opts
+     *     into native server-side joins where eligible instead.
+     *   - `'batched'`: run the base query, then one flat follow-up query per
      *     relation (`WHERE fk = ANY($1)`), stitching children client-side. Wins
      *     when child FK columns are unindexed or result sets are large.
      *
-     * Precedence: per-query `relationLoadStrategy` arg > this config > `'join'`.
+     * Precedence: per-query `relationLoadStrategy` arg > this config > the engine
+     * default. On SQL engines the default is `'join'`; on PowDB the default is the
+     * batched loaders (an ineligible relation falls back to them silently even
+     * under `'join'`).
      */
     relationLoadStrategy?: RelationLoadStrategy;
     /**
@@ -341,11 +345,34 @@ export declare class TransactionClient {
     readonly schema: SchemaMetadata;
     private readonly middlewares;
     private readonly queryOptions?;
+    /**
+     * The parent pool this transaction runs on. Only its `readonly` and
+     * `capabilities` are read (both PowDB-only flags), so the transaction-scoped
+     * proxy pool built by {@link createTxPool} carries them through: without this
+     * a read-only client's `$transaction` writes bypass the E018 guard, and an
+     * older-engine client falls back to ALL_POWDB_CAPABILITIES inside the tx
+     * (emitting join PowQL a pre-0.13 engine rejects). Undefined / absent flags
+     * for a plain pg pool leave the proxy unchanged.
+     */
+    private readonly sourcePool?;
     private readonly tableCache;
     private savepointCounter;
     /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
     private readonly dialect;
-    constructor(client: pg.PoolClient, schema: SchemaMetadata, middlewares: Middleware[], queryOptions?: QueryInterfaceOptions | undefined);
+    constructor(client: pg.PoolClient, schema: SchemaMetadata, middlewares: Middleware[], queryOptions?: QueryInterfaceOptions | undefined, 
+    /**
+     * The parent pool this transaction runs on. Only its `readonly` and
+     * `capabilities` are read (both PowDB-only flags), so the transaction-scoped
+     * proxy pool built by {@link createTxPool} carries them through: without this
+     * a read-only client's `$transaction` writes bypass the E018 guard, and an
+     * older-engine client falls back to ALL_POWDB_CAPABILITIES inside the tx
+     * (emitting join PowQL a pre-0.13 engine rejects). Undefined / absent flags
+     * for a plain pg pool leave the proxy unchanged.
+     */
+    sourcePool?: {
+        readonly readonly?: boolean;
+        readonly capabilities?: unknown;
+    } | undefined);
     /**
      * Get a QueryInterface for a table within this transaction.
      * Uses the dedicated transaction connection instead of the pool.

package/dist/client.js

@@ -104,15 +104,27 @@ export class TransactionClient {
     schema;
     middlewares;
     queryOptions;
+    sourcePool;
     tableCache = new Map();
     savepointCounter = 0;
     /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
     dialect;
-    constructor(client, schema, middlewares, queryOptions) {
+    constructor(client, schema, middlewares, queryOptions, 
+    /**
+     * The parent pool this transaction runs on. Only its `readonly` and
+     * `capabilities` are read (both PowDB-only flags), so the transaction-scoped
+     * proxy pool built by {@link createTxPool} carries them through: without this
+     * a read-only client's `$transaction` writes bypass the E018 guard, and an
+     * older-engine client falls back to ALL_POWDB_CAPABILITIES inside the tx
+     * (emitting join PowQL a pre-0.13 engine rejects). Undefined / absent flags
+     * for a plain pg pool leave the proxy unchanged.
+     */
+    sourcePool) {
         this.client = client;
         this.schema = schema;
         this.middlewares = middlewares;
         this.queryOptions = queryOptions;
+        this.sourcePool = sourcePool;
         this.dialect = queryOptions?.dialect ?? postgresDialect;
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
@@ -192,7 +204,7 @@ export class TransactionClient {
         const client = this.client;
         // Return a minimal pool-compatible object that routes queries
         // through the transaction client
-        return {
+        const txPool = {
             query: async (textOrConfig, values) => {
                 try {
                     if (typeof textOrConfig === 'string') {
@@ -209,6 +221,14 @@ export class TransactionClient {
             },
             connect: () => Promise.resolve(client),
         };
+        // Carry the parent pool's PowDB-only flags through so a transaction-scoped
+        // PowqlInterface reads the same read-only guard and capabilities it would
+        // outside the transaction (a plain pg pool has neither, so nothing changes).
+        if (this.sourcePool?.readonly !== undefined)
+            txPool.readonly = this.sourcePool.readonly;
+        if (this.sourcePool?.capabilities !== undefined)
+            txPool.capabilities = this.sourcePool.capabilities;
+        return txPool;
     }
 }
 // ---------------------------------------------------------------------------
@@ -876,8 +896,10 @@ export class TurbineClient {
                     await client.query(cfg.sql, cfg.params);
                 }
             }
-            // Create the transaction client with typed table accessors
-            const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions);
+            // Create the transaction client with typed table accessors. Pass the
+            // parent pool so its read-only guard + PowDB capabilities flow into the
+            // transaction-scoped proxy pool (see TransactionClient.createTxPool).
+            const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions, this.pool);
             // Dynamically attach table accessors to tx
             for (const tableName of Object.keys(this.schema.tables)) {
                 const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());

package/dist/dialect.d.ts

@@ -302,6 +302,19 @@ export interface Dialect {
      * lateral plan (else E017). PostgreSQL only in this release.
      */
     readonly supportsLateralJoin?: boolean;
+    /**
+     * How this dialect surfaces a query plan for a compiled SELECT. When present,
+     * `QueryInterface.explain()` prepends `prefix` (plus a single space) to the
+     * compiled findMany SQL and runs it as a read, returning the plan text lines.
+     * PostgreSQL / CockroachDB / YugabyteDB and MySQL use `EXPLAIN`, SQLite
+     * `EXPLAIN QUERY PLAN`. Absent means the engine
+     * cannot explain a compiled query in-band (SQL Server, whose SHOWPLAN needs a
+     * separate session toggle), so `QueryInterface.explain()` throws E017.
+     * Optional: dialects that predate this hook keep throwing E017.
+     */
+    readonly explainQuery?: {
+        prefix: string;
+    };
     /** Build a dialect-specific RETURNING clause. Return an empty string when unsupported. */
     buildReturningClause(selection?: string): string;
     /** Build a single-row INSERT statement. Inputs are SQL-ready quoted fragments. */

package/dist/dialect.js

@@ -23,6 +23,7 @@ export const postgresDialect = {
     supportsRLS: true,
     supportsAdvisoryLock: true,
     supportsLateralJoin: true,
+    explainQuery: { prefix: 'EXPLAIN' },
     paramPlaceholder(index) {
         return `$${index}`;
     },

package/dist/errors.d.ts

@@ -23,6 +23,7 @@ export declare const TurbineErrorCode: {
     readonly OPTIMISTIC_LOCK: "TURBINE_E015";
     readonly EXCLUSION_VIOLATION: "TURBINE_E016";
     readonly UNSUPPORTED_FEATURE: "TURBINE_E017";
+    readonly READ_ONLY: "TURBINE_E018";
 };
 export type TurbineErrorCode = (typeof TurbineErrorCode)[keyof typeof TurbineErrorCode];
 /** Base error class for all Turbine errors */
@@ -303,6 +304,41 @@ export declare class UnsupportedFeatureError extends TurbineError {
     readonly dialect: string;
     constructor(feature: string, dialect: string, hint?: string);
 }
+/**
+ * Thrown when a write or DDL statement is refused because the target is
+ * read-only. Two shapes reach here, both on PowDB:
+ *   - an embedded database opened read-only for snapshot serving refuses a write
+ *     with `readonly mode: statement requires a writer …`;
+ *   - a networked read-only role refuses a write with `permission denied: role
+ *     '<role>' cannot execute write statements` (translated by `wrapPowdbError`).
+ * It is also raised locally, before the wire, when a write is issued on a pool
+ * the caller marked read-only (fail-fast). The message carries the engine text
+ * plus a hint to route writes to a writable primary.
+ *
+ * NOT retryable: the same write against the same read-only target fails
+ * identically; route it to a writable primary instead.
+ */
+export declare class ReadOnlyError extends TurbineError {
+    /**
+     * Why the write was refused. `'snapshot'`: the database itself is read-only
+     * (snapshot serving, an embedded `readonly: true` open, or the client-level
+     * fail-fast flag), so NOTHING can write here and writes must route to the
+     * primary. `'rbac'`: the database is writable but THIS connection's role may
+     * not write (per-connection permission), so re-authenticating may suffice.
+     */
+    readonly reason: 'snapshot' | 'rbac';
+    /**
+     * @param detail human-readable description of the refused write (the engine
+     *   message, or a local fail-fast description). A "route writes to a writable
+     *   primary" hint is always appended.
+     * @param options optional driver `cause` to preserve when wrapping a refusal,
+     *   and the refusal `reason` (default `'snapshot'`).
+     */
+    constructor(detail: string, options?: {
+        cause?: unknown;
+        reason?: 'snapshot' | 'rbac';
+    });
+}
 /**
  * Translate a pg driver error into a typed Turbine error.
  * If the error doesn't match a known constraint code, returns it unchanged.

package/dist/errors.js

@@ -23,6 +23,7 @@ export const TurbineErrorCode = {
     OPTIMISTIC_LOCK: 'TURBINE_E015',
     EXCLUSION_VIOLATION: 'TURBINE_E016',
     UNSUPPORTED_FEATURE: 'TURBINE_E017',
+    READ_ONLY: 'TURBINE_E018',
 };
 /**
  * Prefix a human message with its stable error code so logs are greppable
@@ -479,6 +480,44 @@ export class UnsupportedFeatureError extends TurbineError {
         this.dialect = dialect;
     }
 }
+/**
+ * Thrown when a write or DDL statement is refused because the target is
+ * read-only. Two shapes reach here, both on PowDB:
+ *   - an embedded database opened read-only for snapshot serving refuses a write
+ *     with `readonly mode: statement requires a writer …`;
+ *   - a networked read-only role refuses a write with `permission denied: role
+ *     '<role>' cannot execute write statements` (translated by `wrapPowdbError`).
+ * It is also raised locally, before the wire, when a write is issued on a pool
+ * the caller marked read-only (fail-fast). The message carries the engine text
+ * plus a hint to route writes to a writable primary.
+ *
+ * NOT retryable: the same write against the same read-only target fails
+ * identically; route it to a writable primary instead.
+ */
+export class ReadOnlyError extends TurbineError {
+    /**
+     * Why the write was refused. `'snapshot'`: the database itself is read-only
+     * (snapshot serving, an embedded `readonly: true` open, or the client-level
+     * fail-fast flag), so NOTHING can write here and writes must route to the
+     * primary. `'rbac'`: the database is writable but THIS connection's role may
+     * not write (per-connection permission), so re-authenticating may suffice.
+     */
+    reason;
+    /**
+     * @param detail human-readable description of the refused write (the engine
+     *   message, or a local fail-fast description). A "route writes to a writable
+     *   primary" hint is always appended.
+     * @param options optional driver `cause` to preserve when wrapping a refusal,
+     *   and the refusal `reason` (default `'snapshot'`).
+     */
+    constructor(detail, options) {
+        super(TurbineErrorCode.READ_ONLY, `[turbine] ${detail} Route writes to a writable primary.`, {
+            cause: options?.cause,
+        });
+        this.name = 'ReadOnlyError';
+        this.reason = options?.reason ?? 'snapshot';
+    }
+}
 /**
  * Parse column names out of a pg `detail` string like:
  *   "Key (email)=(foo@bar) already exists."

package/dist/index-advisor.d.ts

@@ -58,7 +58,21 @@ export declare function isProbeIndexed(meta: TableMetadata, columns: string[]):
  * should gate on {@link schemaHasIndexInfo} to avoid blanket false positives.
  */
 export declare function findMissingRelationIndexes(schema: SchemaMetadata): MissingRelationIndex[];
-/** True when at least one table in the schema carries index metadata. */
+/**
+ * True when at least one table in the schema carries real, DB-backed index
+ * metadata (i.e. from introspection).
+ *
+ * Excluded (so they never flip the flag, keeping the schema "index-info
+ * unknown"):
+ *   - doc-field expression indexes (`docPath`): they carry no FK-coverage info;
+ *   - code-first DECLARED indexes (`declared`): the SQL DDL generators do NOT
+ *     emit `TableDef.indexes` yet, so a declared index does not reflect a real
+ *     index on the SQL engines. Counting one would arm blanket FK false
+ *     positives (the FK auto-index the push path DID create is then reported
+ *     "missing") and, inversely, suppress warnings for indexes never created.
+ *     A pure code-first schema therefore stays silent exactly as it did before
+ *     `TableDef.indexes` existed.
+ */
 export declare function schemaHasIndexInfo(schema: SchemaMetadata): boolean;
 /**
  * Single-relation check for the dev-mode runtime warning: the (table, columns)

package/dist/index.d.ts

@@ -37,17 +37,17 @@ export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapt
 export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, type RetryOptions, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, type TurbineDriver, withRetry, } from './client.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, DialectIntrospector, DialectMigrator, DialectName, InsertStatementInput, IntrospectOptions as DialectIntrospectOptions, ResultStrategy, StreamableConnection, UpsertStatementInput, } from './dialect.js';
 export { postgresDialect } from './dialect.js';
-export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, type PipelineResultSlot, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, type PipelineResultSlot, ReadOnlyError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 export { type GenerateOptions, generate } from './generate.js';
 export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type HavingClause, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type HavingClause, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
-export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, defineSchema, type ManyToManyDef, type ReferenceDef, type SchemaDef, type TableDef, table, } from './schema-builder.js';
+export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnIndexDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, type DocFieldIndexDef, defineSchema, isDocFieldIndexDef, type ManyToManyDef, type ReferenceDef, type SchemaDef, type SchemaIndexDef, type TableDef, table, } from './schema-builder.js';
 export { schemaDefToMetadata } from './schema-metadata.js';
 export { type AlterColumnDef, type AlterDef, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 export { type DefinedSeed, defineSeed, type SeedFunction } from './seed.js';

package/dist/index.js

@@ -37,7 +37,7 @@ export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapt
 export { TransactionClient, TurbineClient, withRetry, } from './client.js';
 export { postgresDialect } from './dialect.js';
 // Error types
-export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, ReadOnlyError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 // Code generation
 export { generate } from './generate.js';
 // Introspection
@@ -53,7 +53,7 @@ export { validateChannel } from './realtime.js';
 // Schema utilities
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 // Schema builder — define schemas in TypeScript
-export { applyManyToManyRelations, ColumnBuilder, column, defineSchema, 
+export { applyManyToManyRelations, ColumnBuilder, column, defineSchema, isDocFieldIndexDef, 
 // Legacy compat (deprecated — use object format with defineSchema)
 table, } from './schema-builder.js';
 // Schema metadata bridge — defineSchema() → SchemaMetadata without a live DB

package/dist/mssql.js

@@ -472,6 +472,11 @@ export const mssqlDialect = {
     supportsLateralJoin: false,
     // sp_getapplock / sp_releaseapplock exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
+    // No in-band EXPLAIN: SQL Server's SHOWPLAN is a session toggle
+    // (SET SHOWPLAN_ALL ON), not a statement prefix, so a compiled query cannot
+    // be explained in one round-trip. Override the inherited Postgres `EXPLAIN`
+    // to absent → QueryInterface.explain() throws E017.
+    explainQuery: undefined,
     // FOR JSON over zero rows is NULL → coalesced in the relation override.
     aggSupportsInlineOrderBy: false,
     jsonPathSupport: 'limited',

package/dist/mysql.js

@@ -373,6 +373,10 @@ export const mysqlDialect = {
     supportsLateralJoin: false,
     // GET_LOCK / RELEASE_LOCK exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
+    // Plain `EXPLAIN` (one row of tabular plan columns) works on every supported
+    // MySQL 8.0.x; the readable `FORMAT=TREE` variant only exists from 8.0.16 and
+    // the engine floor here is 8.0.0. Plan text is a diagnostic, not a contract.
+    explainQuery: { prefix: 'EXPLAIN' },
     // JSON_ARRAYAGG has no inline ORDER BY argument → force the inner-subquery
     // rewrite for every ordered to-many relation.
     aggSupportsInlineOrderBy: false,