turbine-orm 0.34.0 → 0.36.0

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

@@ -8,6 +8,15 @@
 import type { WithOptions } from './query/types.js';
 import { type RelationDef, type SchemaMetadata, type TableMetadata } from './schema.js';
 export type DialectName = 'postgresql' | 'mysql' | 'sqlite' | (string & {});
+/**
+ * A write statement's returning/output selection. `'*'` returns every column
+ * (the historical default, byte-identical SQL). A `string[]` is an explicit,
+ * SQL-ready quoted column list used to exclude PII-tagged columns from a
+ * write's returned row at the SQL level, so PII never crosses the wire
+ * unrequested. Each dialect renders it into its own returning surface
+ * (`RETURNING …`, `OUTPUT INSERTED.…`).
+ */
+export type ReturningSelection = '*' | readonly string[];
 export interface InsertStatementInput {
     /** SQL-ready quoted table name. */
     table: string;
@@ -16,7 +25,7 @@ export interface InsertStatementInput {
     /** SQL-ready parameter placeholders/expressions for VALUES. */
     valuePlaceholders: string[];
     /** Optional SQL-ready RETURNING selection. */
-    returning?: string;
+    returning?: ReturningSelection;
 }
 export interface BulkInsertStatementInput {
     /** SQL-ready quoted table name. */
@@ -30,7 +39,7 @@ export interface BulkInsertStatementInput {
     /** Skip duplicate rows when supported by the dialect. */
     skipDuplicates?: boolean;
     /** Optional SQL-ready RETURNING selection. */
-    returning?: string;
+    returning?: ReturningSelection;
 }
 export interface BuiltStatement {
     sql: string;
@@ -56,7 +65,7 @@ export interface UpsertStatementInput {
      */
     updateWhere?: string;
     /** Optional SQL-ready RETURNING selection. */
-    returning?: string;
+    returning?: ReturningSelection;
 }
 export interface ColumnTypeInput {
     /** Schema-builder column type name (PostgreSQL-native in the root package). */
@@ -136,7 +145,7 @@ export interface UpdateStatementInput {
     /** SQL-ready WHERE fragment INCLUDING the leading ` WHERE ` (or '' for none). */
     whereSql: string;
     /** SQL-ready returning selection (default `*`). */
-    returning?: string;
+    returning?: ReturningSelection;
 }
 /**
  * Inputs for {@link Dialect.buildDeleteStatement} — full DELETE assembly. SQL Server
@@ -148,7 +157,7 @@ export interface DeleteStatementInput {
     /** SQL-ready WHERE fragment INCLUDING the leading ` WHERE ` (or '' for none). */
     whereSql: string;
     /** SQL-ready returning selection (default `*`). */
-    returning?: string;
+    returning?: ReturningSelection;
 }
 /**
  * Inputs for {@link Dialect.buildLimitOffset} — the trailing pagination clause of an
@@ -302,8 +311,21 @@ 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;
+    buildReturningClause(selection?: ReturningSelection): string;
     /** Build a single-row INSERT statement. Inputs are SQL-ready quoted fragments. */
     buildInsertStatement(input: InsertStatementInput): string;
     /** Build a multi-row bulk INSERT statement and its dialect-shaped params. */

package/dist/dialect.js

@@ -23,6 +23,7 @@ export const postgresDialect = {
     supportsRLS: true,
     supportsAdvisoryLock: true,
     supportsLateralJoin: true,
+    explainQuery: { prefix: 'EXPLAIN' },
     paramPlaceholder(index) {
         return `$${index}`;
     },
@@ -68,7 +69,7 @@ export const postgresDialect = {
         return `COALESCE((${subquery}), ${fallback})`;
     },
     buildReturningClause(selection = '*') {
-        return ` RETURNING ${selection}`;
+        return ` RETURNING ${selection === '*' ? '*' : selection.join(', ')}`;
     },
     buildInsertStatement(input) {
         return `INSERT INTO ${input.table} (${input.columns.join(', ')}) VALUES (${input.valuePlaceholders.join(', ')})${this.buildReturningClause(input.returning)}`;

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/generate.js

@@ -161,8 +161,13 @@ export function generateTypes(schema, options) {
         for (const col of table.columns) {
             const pkNote = table.primaryKey.includes(col.name) ? ' (primary key)' : '';
             const nullNote = col.nullable ? ' (nullable)' : '';
-            lines.push(`  /** Column: ${col.name} — ${col.pgType}${pkNote}${nullNote} */`);
-            lines.push(`  ${col.field}: ${columnTsType(col, schema.enums)};`);
+            // PII columns are excluded from default projections, so the field is
+            // absent unless the query names it in `select` or passes `includePii`.
+            // The emitted type marks it optional so it tells the truth about absence.
+            const piiNote = col.pii ? ' (PII: absent unless selected or includePii)' : '';
+            const optional = col.pii ? '?' : '';
+            lines.push(`  /** Column: ${col.name}, ${col.pgType}${pkNote}${nullNote}${piiNote} */`);
+            lines.push(`  ${col.field}${optional}: ${columnTsType(col, schema.enums)};`);
         }
         lines.push('}');
         lines.push('');
@@ -524,6 +529,17 @@ export function generateMetadata(schema, options) {
             lines.push(`        { name: '${escSQ(idx.name)}', columns: [${idx.columns.map((c) => `'${escSQ(c)}'`).join(', ')}], unique: ${idx.unique}, definition: ${JSON.stringify(idx.definition)} },`);
         }
         lines.push('      ],');
+        // checks: introspected named CHECK constraints. Emitted only when present
+        // (byte-stable for check-less tables) and sorted by name so `--no-timestamp`
+        // output is deterministic regardless of catalog row order.
+        if (table.checks && table.checks.length > 0) {
+            const sortedChecks = [...table.checks].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+            lines.push('      checks: [');
+            for (const chk of sortedChecks) {
+                lines.push(`        { name: '${escSQ(chk.name)}', expression: ${JSON.stringify(chk.expression)} },`);
+            }
+            lines.push('      ],');
+        }
         // isView — read-only marker; the runtime write guard reads it.
         if (table.isView)
             lines.push('      isView: true,');
@@ -727,6 +743,11 @@ function serializeColumn(col) {
     if (col.generationExpression !== undefined) {
         parts.push(`generationExpression: '${escSQ(col.generationExpression)}'`);
     }
+    // PII marker: emitted only when set, so untagged schemas stay byte-identical.
+    // Introspection never sets this (code-first declaration), but a metadata
+    // object built from `defineSchema` (pii: true) carries it through codegen.
+    if (col.pii)
+        parts.push(`pii: true`);
     if (col.maxLength !== undefined)
         parts.push(`maxLength: ${col.maxLength}`);
     return `{ ${parts.join(', ')} }`;

package/dist/index.d.ts

@@ -37,19 +37,19 @@ 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 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 AlterColumnDef, type AlterDef, DestructivePushRefusal, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 export { type DefinedSeed, defineSeed, type SeedFunction } from './seed.js';
 export { type TurbineHttpOptions, turbineHttp } from './serverless.js';
 export { buildTypedSql, TypedSqlQuery } from './typed-sql.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
@@ -59,7 +59,7 @@ table, } from './schema-builder.js';
 // Schema metadata bridge — defineSchema() → SchemaMetadata without a live DB
 export { schemaDefToMetadata } from './schema-metadata.js';
 // Schema SQL — generate DDL, diff, and push
-export { schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
+export { DestructivePushRefusal, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 // Seed helper
 export { defineSeed } from './seed.js';
 // Serverless / edge factory

package/dist/mssql.js

@@ -448,6 +448,23 @@ function mssqlColumnType(type, maxLength) {
 // ---------------------------------------------------------------------------
 // mssqlDialect — the full Dialect contract for SQL Server 2016+
 // ---------------------------------------------------------------------------
+/**
+ * Render the SQL Server `OUTPUT` clause for a write's returning selection.
+ * `'*'` → ` OUTPUT INSERTED.*` (byte-identical to the historical default); a
+ * quoted column list → ` OUTPUT INSERTED.[c1], INSERTED.[c2]`; each column
+ * carries its own `INSERTED.`/`DELETED.` prefix (a bare comma list is invalid
+ * T-SQL). Used to exclude PII columns from a write's returned row. Empty
+ * selection → no clause.
+ */
+function mssqlOutput(returning, alias) {
+    if (!returning)
+        return '';
+    if (returning === '*')
+        return ` OUTPUT ${alias}.*`;
+    if (returning.length === 0)
+        return '';
+    return ` OUTPUT ${returning.map((col) => `${alias}.${col}`).join(', ')}`;
+}
 /**
  * SQL Server 2016+ implementation of the {@link Dialect} contract. Bracket
  * identifier quoting (`[…]`), named `@pN` placeholders, the `FOR JSON PATH`
@@ -472,6 +489,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',
@@ -506,7 +528,7 @@ export const mssqlDialect = {
         return '';
     },
     buildInsertStatement(input) {
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         return `INSERT INTO ${input.table} (${input.columns.join(', ')})${out} VALUES (${input.valuePlaceholders.join(', ')})`;
     },
     buildBulkInsertStatement(input) {
@@ -526,7 +548,7 @@ export const mssqlDialect = {
         const placeholders = input.rowValues
             .map((row) => `(${row.map(() => this.paramPlaceholder(++n)).join(', ')})`)
             .join(', ');
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         // skipDuplicates has no single-statement equivalent here; ignored (documented).
         return {
             sql: `INSERT INTO ${input.table} (${input.columns.join(', ')})${out} VALUES ${placeholders}`,
@@ -541,7 +563,7 @@ export const mssqlDialect = {
         const on = input.conflictColumns.map((c) => `T.${c} = S.${c}`).join(' AND ');
         const insertCols = input.insertColumns.join(', ');
         const sourceVals = input.insertColumns.map((c) => `S.${c}`).join(', ');
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         return (`MERGE INTO ${input.table} AS T ` +
             `USING (VALUES (${input.valuePlaceholders.join(', ')})) AS S (${insertCols}) ` +
             `ON (${on}) ` +
@@ -552,11 +574,11 @@ export const mssqlDialect = {
     // UPDATE/DELETE inject OUTPUT mid-statement (between SET and WHERE / FROM and
     // WHERE) — a trailing clause would be invalid T-SQL.
     buildUpdateStatement(input) {
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         return `UPDATE ${input.table} SET ${input.setClauses.join(', ')}${out}${input.whereSql}`;
     },
     buildDeleteStatement(input) {
-        const out = input.returning ? ` OUTPUT DELETED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'DELETED');
         return `DELETE FROM ${input.table}${out}${input.whereSql}`;
     },
     // SQL Server has no LIMIT — emit OFFSET/FETCH, injecting a stable ORDER BY when

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,