turbine-orm 0.34.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.

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.d.ts

@@ -37,13 +37,13 @@ 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';

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

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,

package/dist/powdb.d.ts

@@ -252,11 +252,13 @@ export interface PowdbCapabilities {
     docFieldIndexes: boolean;
     /** ≥ 0.10: `schema` / `describe` introspection statements. */
     introspection: boolean;
+    /** ≥ 0.13: server-side joins, hash-accelerated and bounded. */
+    serverJoins: boolean;
     /** Networked only: server ≥ 0.13 AND the client exposes `queryNativeRaw`. */
     nativeRaw: boolean;
 }
 /** The feature-gate capability keys (everything except the version/nativeRaw metadata). */
-type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection';
+type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins';
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
  * for a directly-constructed {@link PowdbPool} / {@link PowdbEmbeddedPool} that
@@ -439,6 +441,15 @@ export interface PowdbPoolOptions {
      * Default `false` (typed-error-only).
      */
     retryStaleReads?: boolean;
+    /**
+     * Mark this pool read-only: {@link PowqlInterface}'s exec seam then fails a
+     * write (or a tx-control `begin`) fast with a {@link ReadOnlyError} (E018)
+     * before it reaches the wire. An `{ embedded, readonly: true }` target forces
+     * this true; a networked pool bound to a read-only role can also set it so
+     * writes are rejected locally instead of round-tripping to the engine's
+     * refusal. Default `false`.
+     */
+    readonly?: boolean;
 }
 /**
  * A {@link PgCompatPool} backed by a `@zvndev/powdb-client` `Pool`. The query
@@ -476,6 +487,13 @@ export declare class PowdbPool implements PgCompatPool {
     readonly capabilities: PowdbCapabilities;
     /** Opt-in first-statement-read replay on a stale wire frame (read by {@link PowqlInterface}). */
     readonly retryStaleReads: boolean;
+    /**
+     * True when the caller marked this pool read-only (`readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own read-only-role refusal (mapped by
+     * {@link wrapPowdbError}) is the backstop for raw / injected paths.
+     */
+    readonly readonly: boolean;
     constructor(pool: PowdbClientPool, toParam?: (v: unknown, i: number) => PowdbParam, options?: PowdbPoolOptions);
     /**
      * Run one statement on `c`, choosing the lossless native typed wire when the
@@ -503,6 +521,14 @@ interface EmbeddedQueryResult {
     affected?: bigint;
     message?: string;
 }
+/**
+ * The embedded addon's native typed result (`@zvndev/powdb-embedded` ≥ 0.14).
+ * Mirrors {@link PowdbRawNativeResult}, the same tagged {@link PowdbWireValue}
+ * cells (embedded `bytes` arrive as a `Buffer`, which IS a `Uint8Array`, so the
+ * decode path is unchanged), including the `message` kind for DDL / status
+ * replies, which {@link adaptNativeResult}'s default branch handles at runtime.
+ */
+type EmbeddedNativeResult = PowdbRawNativeResult;
 /** A single in-process embedded database handle (`@zvndev/powdb-embedded`). */
 interface EmbeddedDatabase {
     query(powql: string): EmbeddedQueryResult;
@@ -511,6 +537,32 @@ interface EmbeddedDatabase {
     isPoisoned(): boolean;
     /** WAL durability selector — `@zvndev/powdb-embedded` ≥ 0.7.1. */
     setSyncMode?(mode: string): void;
+    /**
+     * Lossless typed native wire (`@zvndev/powdb-embedded` ≥ 0.14). All optional
+     * and feature-detected: an older addon omits them, so {@link PowdbEmbeddedPool}
+     * falls back to {@link materializePowql} + {@link query}. `queryWithParams`
+     * binds positional `$N` params as {@link PowdbParam} values (the NativeParam
+     * union) instead of materializing literals.
+     */
+    queryNative?(powql: string): EmbeddedNativeResult;
+    queryReadonlyNative?(powql: string): EmbeddedNativeResult;
+    queryWithParams?(powql: string, params: PowdbParam[]): EmbeddedNativeResult;
+    /** Checkpoint-flushing close (`@zvndev/powdb-embedded` ≥ 0.14). Optional (feature-detected). */
+    close?(): void;
+}
+interface EmbeddedModule {
+    Database: {
+        open(dir: string): EmbeddedDatabase;
+        /** Open with a per-query memory budget — `@zvndev/powdb-embedded` ≥ 0.7.1. */
+        openWithMemoryLimit?(dir: string, limitBytes: number): EmbeddedDatabase;
+        /**
+         * Open a read-only handle for snapshot serving (`@zvndev/powdb-embedded` ≥
+         * 0.14). Optional (feature-detected); a write through such a handle is
+         * refused with `readonly mode: statement requires a writer …` (→ E018).
+         */
+        openReadOnly?(dir: string): EmbeddedDatabase;
+        openReadOnlyWithMemoryLimit?(dir: string, limitBytes: number): EmbeddedDatabase;
+    };
 }
 /**
  * Encode a JS value as a **PowQL literal** for the embedded driver, which takes
@@ -539,10 +591,14 @@ export declare function encodePowqlLiteral(value: unknown): string;
 export declare function materializePowql(powql: string, params: unknown[]): string;
 /**
  * A {@link PgCompatPool} backed by an in-process `@zvndev/powdb-embedded`
- * `Database`. The embedded addon takes **no params array** — its `query(powql)`
- * accepts only a string — so this pool materializes each positional `$N` into a
- * PowQL literal via {@link materializePowql} before handing the text to the
- * engine. One handle, single connection: transaction keywords (`begin`/`commit`/
+ * `Database`. On the addon's typed native wire (≥ 0.14, when
+ * `capabilities.nativeRaw` is set) this pool binds positional `$N` params via
+ * `queryWithParams` and decodes the typed cells, exactly like the networked
+ * transport. On an older addon (no `queryWithParams`) it falls back to the
+ * legacy string wire, which takes **no params array** (its `query(powql)`
+ * accepts only a string), so each positional `$N` is materialized into a PowQL
+ * literal via {@link materializePowql} before the text is handed to the engine.
+ * One handle, single connection: transaction keywords (`begin`/`commit`/
  * `rollback`) are issued serially as ordinary queries.
  */
 export declare class PowdbEmbeddedPool implements PgCompatPool {
@@ -563,14 +619,24 @@ export declare class PowdbEmbeddedPool implements PgCompatPool {
     private readonly poolHoldRef;
     /**
      * Feature capabilities of the embedded engine (resolved from the addon
-     * package version). `nativeRaw` is always false: the embedded addon exposes
-     * no native typed-wire surface (its rows are `string[][]`, the legacy wire).
+     * package version). `nativeRaw` is true when the addon is ≥ 0.14 and the
+     * opened handle exposes `queryWithParams` (the typed native wire); an older
+     * addon has no such method, so it stays false and the legacy string wire is
+     * used.
      */
     readonly capabilities: PowdbCapabilities;
     /** Carried for surface uniformity with {@link PowdbPool}; inert on embedded (no protocol_error frames). */
     readonly retryStaleReads: boolean;
+    /**
+     * True when this pool was opened read-only (an `{ embedded, readonly: true }`
+     * target, or a directly-constructed pool passed `readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own refusal (mapped by {@link wrapPowdbError}) is the
+     * backstop for raw / injected paths.
+     */
+    readonly readonly: boolean;
     constructor(db: EmbeddedDatabase, options?: PowdbPoolOptions);
-    /** Materialize `$N` params and hand the PowQL to the in-process engine. */
+    /** Run the PowQL on the in-process engine, choosing the native or legacy wire. */
     private exec;
     /**
      * Run one statement, gating transaction control. `holdRef` scopes the gate
@@ -586,7 +652,17 @@ export declare class PowdbEmbeddedPool implements PgCompatPool {
 export { introspectPowdbDatabase, type PowdbExec, type PowdbIntrospectOptions, } from './powdb-introspect.js';
 export { PowqlInterface } from './powql.js';
 /** Options for {@link turbinePowDB}. */
-export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
+export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited' | 'relationLoadStrategy'> {
+    /**
+     * Client-level default `with`-relation load strategy. On PowDB the default is
+     * the batched N+1 loaders; setting `'join'` opts INTO native PowQL server-side
+     * joins for eligible top-level relations (ineligible ones, e.g. a paged parent
+     * or a nested `with`, fall back to the loaders per-relation and silently). A
+     * per-query `relationLoadStrategy` arg still overrides this. Requires an engine
+     * that advertises `serverJoins` (PowDB ≥ 0.13); a per-query `'join'` on an
+     * older engine throws E017, a client-level default silently falls back.
+     */
+    relationLoadStrategy?: TurbineConfig['relationLoadStrategy'];
     /** Max pooled connections (default 10). Networked transport only. */
     connectionLimit?: number;
     /**
@@ -623,6 +699,18 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
      * E017).
      */
     assumeEngineVersion?: string;
+    /**
+     * Mark the client read-only: a write (or a transaction `begin`) fails fast
+     * locally with a {@link ReadOnlyError} (E018) before it reaches the wire,
+     * rather than round-tripping to the engine's refusal. Works on both
+     * transports (a networked pool bound to a read-only role, or an embedded
+     * handle). An `{ embedded, readonly: true }` target implies this. Default
+     * `false`.
+     *
+     * Ignored when you inject an already-constructed {@link PowdbPool} (it carries
+     * its own {@link PowdbPoolOptions}); set it on that pool's constructor instead.
+     */
+    readonly?: boolean;
     /**
      * Driver-module injection for the networked target forms (URL / host+port):
      * bypasses the dynamic `import('@zvndev/powdb-client')` and uses this object
@@ -630,6 +718,14 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
      * connections) and advanced embedding; everyday callers never set it.
      */
     powdbClientModule?: PowdbModule;
+    /**
+     * Driver-module injection for the **embedded** target form (`{ embedded }`):
+     * bypasses the dynamic `import('@zvndev/powdb-embedded')` and uses this object
+     * as the addon module instead. Intended for tests (a fake `Database` factory
+     * that records how the handle was opened) and advanced embedding; everyday
+     * callers never set it. The symmetric counterpart to {@link powdbClientModule}.
+     */
+    powdbEmbeddedModule?: EmbeddedModule;
 }
 /**
  * Selects the **embedded** transport — an in-process `@zvndev/powdb-embedded`
@@ -655,6 +751,16 @@ export interface TurbinePowdbEmbeddedTarget {
     syncMode?: 'full' | 'normal' | 'off';
     /** Per-query memory budget in bytes (requires `@zvndev/powdb-embedded` ≥ 0.7.1). */
     memoryLimit?: number;
+    /**
+     * Open the data directory read-only for snapshot serving (requires
+     * `@zvndev/powdb-embedded` ≥ 0.14: `openReadOnly` / `openReadOnlyWithMemoryLimit`).
+     * A write through a read-only handle is refused by the engine with
+     * `readonly mode: statement requires a writer …` (→ {@link ReadOnlyError}, E018),
+     * and Turbine additionally fails writes fast locally (this implies the pool's
+     * `readonly` flag). Meaningless together with `syncMode` (a read-only engine
+     * never writes), setting both throws a {@link ValidationError}.
+     */
+    readonly?: boolean;
 }
 /**
  * Bind Turbine to PowDB. `target` is one of: