turbine-orm 0.40.1 → 0.41.0

package/dist/introspect.d.ts

@@ -8,13 +8,54 @@
  * This is the foundation of `npx turbine generate`.
  */
 import { type Dialect } from './dialect.js';
-import { type ColumnMetadata, type ReferentialAction, type RelationDef, type SchemaMetadata } from './schema.js';
+import { type ColumnMetadata, type IndexMetadata, type ReferentialAction, type RelationDef, type SchemaMetadata } from './schema.js';
 /**
  * Map a `pg_constraint.confdeltype` / `confupdtype` character to a
  * {@link ReferentialAction}. Postgres encodes: `a` = NO ACTION, `r` = RESTRICT,
  * `c` = CASCADE, `n` = SET NULL, `d` = SET DEFAULT.
  */
 export declare function pgConfActionToReferential(ch: string): ReferentialAction;
+/**
+ * Migration-bookkeeping tables that introspection drops by default: Turbine's
+ * own `_turbine_migrations` / `_turbine_metrics` and Prisma's
+ * `_prisma_migrations`. These are almost never meant to be surfaced as typed
+ * accessors, and a fresh migrate-from-Prisma introspection would otherwise emit
+ * a `PrismaMigrations` entity plus stray FK-derived relations on neighbours.
+ *
+ * A table named here is dropped UNLESS it is explicitly listed in
+ * `options.include` (`include` is the escape hatch, no separate flag), and
+ * naming a default-excluded table restores its old generated output byte for
+ * byte. The list is deliberately tight (exactly these three); leading-
+ * underscore tables are legitimate user tables and are never blanket-excluded.
+ */
+export declare const DEFAULT_EXCLUDED_TABLES: readonly ["_turbine_migrations", "_prisma_migrations", "_turbine_metrics"];
+/** The include / exclude filters shared by every introspector's table selection. */
+export interface TableFilterOptions {
+    /** Tables to include (empty/undefined = all). Applied first. */
+    include?: string[];
+    /** Tables the user asked to exclude. Applied after include. */
+    exclude?: string[];
+}
+/**
+ * The single authority for turning a raw list of candidate table names into the
+ * introspected set, shared by the Postgres catalog reader and every engine
+ * introspector (SQLite / MySQL / MSSQL / PowDB) so all surfaces agree.
+ *
+ * Order of operations:
+ *   1. `include` filter: when non-empty, keep only the named tables.
+ *   2. user `exclude`: drop anything the caller listed.
+ *   3. {@link DEFAULT_EXCLUDED_TABLES}: drop migration bookkeeping tables,
+ *      EXCEPT any that the caller explicitly named in `include` (the escape
+ *      hatch that restores the pre-0.41 output for those tables).
+ */
+export declare function applyTableFilters(names: string[], options?: TableFilterOptions): string[];
+/**
+ * The subset of {@link DEFAULT_EXCLUDED_TABLES} that were present in `names` but
+ * dropped by {@link applyTableFilters} (i.e. not re-added via `include`). Pure
+ * helper so the CLI can report "skipped internal table X" without re-deriving
+ * the filtering rule.
+ */
+export declare function defaultExcludedTablesPresent(names: string[], options?: TableFilterOptions): string[];
 export interface IntrospectOptions {
     /** Postgres connection string */
     connectionString: string;
@@ -31,6 +72,23 @@ export interface IntrospectOptions {
      * the generated `findUnique`-family accessor types.
      */
     includeViews?: boolean;
+    /**
+     * Opt OUT of the unique-FK → `hasOne` flip (F2). By default (`false`)
+     * introspection emits a to-one (`hasOne`) relation on the parent side when a
+     * child's foreign-key column set is EXACTLY covered by a UNIQUE constraint or
+     * a non-partial, non-expression UNIQUE index, matching Prisma one-to-one
+     * introspection. Set to `true` to keep the pre-0.41 behavior where every such
+     * relation was emitted as `hasMany` (a to-many array). See
+     * {@link detectUniqueForeignKeySets}.
+     */
+    legacyToManyUniques?: boolean;
+    /**
+     * Called with any {@link DEFAULT_EXCLUDED_TABLES} that were present in the
+     * database but dropped from this run (F12), so the CLI can print a
+     * "skipped internal table X (add it to include to keep it)" note. Not invoked
+     * when the set is empty. Postgres path only for now.
+     */
+    onDefaultTableExclusion?: (tables: string[]) => void;
     /**
      * Dialect whose {@link Dialect.introspector} drives the catalog reads.
      * Defaults to {@link postgresDialect}. Engines plug their own introspector
@@ -81,6 +139,30 @@ export declare function relationNameFromColumn(column: string): string;
  * payload), so the legacy-first naming keeps it instead of renaming.
  */
 export declare function isUnknownTsType(tsType: string): boolean;
+/**
+ * Parse the column list of a PLAIN unique index from its `pg_indexes.indexdef`,
+ * returning `null` for anything that does NOT guarantee at-most-one child row:
+ *
+ *   - a PARTIAL index (has a `WHERE` clause): only unique within the predicate;
+ *   - an EXPRESSION index (`lower(email)`, `(a || b)`): the uniqueness is on the
+ *     expression, not the raw FK column set.
+ *
+ * Anchors on the `USING <method> (` clause the same way
+ * {@link describeIndexDefMismatch} does, so a partial index's `WHERE (...)`
+ * parentheses are never mistaken for the column list. Every column token must be
+ * a bare or double-quoted identifier; anything else (a function call, an
+ * operator expression) fails the check and yields `null`.
+ */
+export declare function parsePlainUniqueIndexColumns(indexdef: string): string[] | null;
+/**
+ * Assemble, per table, every column set that EXACTLY guarantees at-most-one row:
+ * the primary key, every UNIQUE constraint, and every PLAIN (non-partial,
+ * non-expression) UNIQUE index. Consumed by
+ * {@link buildRelationsFromForeignKeys} to flip a child relation whose FK column
+ * set matches one of these sets from `hasMany` to `hasOne` (F2, Prisma
+ * one-to-one parity).
+ */
+export declare function detectUniqueForeignKeySets(pkByTable: Map<string, string[]>, uniqueByTable: Map<string, string[][]>, indexesByTable: Map<string, IndexMetadata[]>): Map<string, string[][]>;
 /**
  * Build the belongsTo/hasMany relation maps for every table from its foreign
  * keys. Naming rules (LEGACY-FIRST — a relation name that previously worked at
@@ -111,11 +193,19 @@ export declare function isUnknownTsType(tsType: string): boolean;
  *   guarantee relations never shadow concrete-typed scalar columns.
  * @param unknownTypedFieldsByTable subset of the column fields whose tsType is
  *   `unknown` (json/jsonb) — legacy shadows of these are preserved (rule 2).
+ * @param uniqueSetsByTable when provided (F2), the child-table column sets that
+ *   guarantee at-most-one row (PK + unique constraints + plain unique indexes,
+ *   from {@link detectUniqueForeignKeySets}). A reverse relation whose FK column
+ *   set EXACTLY matches one of the child's unique sets is emitted as `hasOne`
+ *   (to-one) instead of `hasMany`, and named with the SINGULAR of the child
+ *   table (falling back to the legacy plural name on collision). Omit it (the
+ *   engine introspectors and `defineSchema` path do) to keep every reverse
+ *   relation `hasMany`.
  */
 export declare function buildRelationsFromForeignKeys(foreignKeys: ForeignKeyEntry[], columnFieldsByTable: Map<string, Set<string>>, fkActions?: Map<string, {
     onDelete: ReferentialAction;
     onUpdate: ReferentialAction;
-}>, unknownTypedFieldsByTable?: Map<string, Set<string>>): Map<string, Record<string, RelationDef>>;
+}>, unknownTypedFieldsByTable?: Map<string, Set<string>>, uniqueSetsByTable?: Map<string, string[][]>): Map<string, Record<string, RelationDef>>;
 /**
  * Conservative auto-`manyToMany` detection over pure junction tables, shared
  * by the Postgres introspector, the engine introspectors (SQLite / MySQL /

package/dist/introspect.js

@@ -176,6 +176,61 @@ const SQL_ENUMS = `
   ORDER BY t.typname, e.enumsortorder
 `;
 // ---------------------------------------------------------------------------
+// Default table exclusions (F12)
+// ---------------------------------------------------------------------------
+/**
+ * Migration-bookkeeping tables that introspection drops by default: Turbine's
+ * own `_turbine_migrations` / `_turbine_metrics` and Prisma's
+ * `_prisma_migrations`. These are almost never meant to be surfaced as typed
+ * accessors, and a fresh migrate-from-Prisma introspection would otherwise emit
+ * a `PrismaMigrations` entity plus stray FK-derived relations on neighbours.
+ *
+ * A table named here is dropped UNLESS it is explicitly listed in
+ * `options.include` (`include` is the escape hatch, no separate flag), and
+ * naming a default-excluded table restores its old generated output byte for
+ * byte. The list is deliberately tight (exactly these three); leading-
+ * underscore tables are legitimate user tables and are never blanket-excluded.
+ */
+export const DEFAULT_EXCLUDED_TABLES = ['_turbine_migrations', '_prisma_migrations', '_turbine_metrics'];
+/**
+ * The single authority for turning a raw list of candidate table names into the
+ * introspected set, shared by the Postgres catalog reader and every engine
+ * introspector (SQLite / MySQL / MSSQL / PowDB) so all surfaces agree.
+ *
+ * Order of operations:
+ *   1. `include` filter: when non-empty, keep only the named tables.
+ *   2. user `exclude`: drop anything the caller listed.
+ *   3. {@link DEFAULT_EXCLUDED_TABLES}: drop migration bookkeeping tables,
+ *      EXCEPT any that the caller explicitly named in `include` (the escape
+ *      hatch that restores the pre-0.41 output for those tables).
+ */
+export function applyTableFilters(names, options = {}) {
+    let result = names;
+    const includeSet = options.include?.length ? new Set(options.include) : null;
+    if (includeSet) {
+        result = result.filter((t) => includeSet.has(t));
+    }
+    if (options.exclude?.length) {
+        const excludeSet = new Set(options.exclude);
+        result = result.filter((t) => !excludeSet.has(t));
+    }
+    // Default exclusions never override an explicit include.
+    const defaults = new Set(DEFAULT_EXCLUDED_TABLES);
+    result = result.filter((t) => !defaults.has(t) || (includeSet?.has(t) ?? false));
+    return result;
+}
+/**
+ * The subset of {@link DEFAULT_EXCLUDED_TABLES} that were present in `names` but
+ * dropped by {@link applyTableFilters} (i.e. not re-added via `include`). Pure
+ * helper so the CLI can report "skipped internal table X" without re-deriving
+ * the filtering rule.
+ */
+export function defaultExcludedTablesPresent(names, options = {}) {
+    const includeSet = options.include?.length ? new Set(options.include) : null;
+    const present = new Set(names);
+    return DEFAULT_EXCLUDED_TABLES.filter((t) => present.has(t) && !(includeSet?.has(t) ?? false));
+}
+// ---------------------------------------------------------------------------
 // Main introspection function
 // ---------------------------------------------------------------------------
 /**
@@ -243,16 +298,18 @@ export async function introspectPostgresCatalog(options) {
                 onUpdate: pgConfActionToReferential(row.confupdtype),
             });
         }
-        // Filter tables by include/exclude. Views/matviews join the base tables as
-        // candidates so include/exclude apply uniformly.
-        let tableNames = [...tablesResult.rows.map((r) => r.table_name), ...viewNameSet];
-        if (options.include?.length) {
-            const includeSet = new Set(options.include);
-            tableNames = tableNames.filter((t) => includeSet.has(t));
-        }
-        if (options.exclude?.length) {
-            const excludeSet = new Set(options.exclude);
-            tableNames = tableNames.filter((t) => !excludeSet.has(t));
+        // Filter tables by include/exclude + default bookkeeping-table exclusions
+        // (F12). Views/matviews join the base tables as candidates so the filters
+        // apply uniformly.
+        const candidateTables = [
+            ...tablesResult.rows.map((r) => r.table_name),
+            ...viewNameSet,
+        ];
+        const tableNames = applyTableFilters(candidateTables, options);
+        if (options.onDefaultTableExclusion) {
+            const skipped = defaultExcludedTablesPresent(candidateTables, options);
+            if (skipped.length > 0)
+                options.onDefaultTableExclusion(skipped);
         }
         const tableSet = new Set(tableNames);
         // ----- Group columns by table -----
@@ -407,7 +464,13 @@ export async function introspectPostgresCatalog(options) {
             // main, so only genuine json/jsonb columns qualify as historical shadows.
             unknownTypedFieldsByTable.set(tbl, new Set(cols.filter((c) => isUnknownTsType(c.tsType) && !Object.hasOwn(enums, c.pgType)).map((c) => c.field)));
         }
-        const relationsByTable = buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable);
+        // F2: unless the caller opts out, detect child FK column sets that a unique
+        // constraint / plain unique index exactly covers, so the reverse relation is
+        // emitted as a one-to-one (`hasOne`) instead of `hasMany`.
+        const uniqueSetsByTable = options.legacyToManyUniques
+            ? undefined
+            : detectUniqueForeignKeySets(pkByTable, uniqueByTable, indexesByTable);
+        const relationsByTable = buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable, uniqueSetsByTable);
         // ----- Conservative many-to-many auto-detection (PURELY ADDITIVE) -----
         //
         // Auto-detecting m2m is a footgun: any table with two FKs *looks* like a
@@ -537,6 +600,92 @@ function upperFirst(s) {
 export function isUnknownTsType(tsType) {
     return tsType === 'unknown' || tsType === 'unknown | null';
 }
+// ---------------------------------------------------------------------------
+// Unique-foreign-key detection for one-to-one relations (F2)
+// ---------------------------------------------------------------------------
+/** True when two column lists cover the same set (order-insensitive, no dupes). */
+function columnSetsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const bs = new Set(b);
+    return a.every((c) => bs.has(c));
+}
+/**
+ * Parse the column list of a PLAIN unique index from its `pg_indexes.indexdef`,
+ * returning `null` for anything that does NOT guarantee at-most-one child row:
+ *
+ *   - a PARTIAL index (has a `WHERE` clause): only unique within the predicate;
+ *   - an EXPRESSION index (`lower(email)`, `(a || b)`): the uniqueness is on the
+ *     expression, not the raw FK column set.
+ *
+ * Anchors on the `USING <method> (` clause the same way
+ * {@link describeIndexDefMismatch} does, so a partial index's `WHERE (...)`
+ * parentheses are never mistaken for the column list. Every column token must be
+ * a bare or double-quoted identifier; anything else (a function call, an
+ * operator expression) fails the check and yields `null`.
+ */
+export function parsePlainUniqueIndexColumns(indexdef) {
+    // Partial index: uniqueness is scoped to the WHERE predicate.
+    if (/\bWHERE\b/i.test(indexdef))
+        return null;
+    const paren = indexdef.match(/USING\s+\w+\s*\(([^)]*)\)/i);
+    if (!paren)
+        return null;
+    const tokens = paren[1].split(',').map((c) => c
+        .trim()
+        .replace(/\s+(ASC|DESC|NULLS\s+(FIRST|LAST))\b/gi, '')
+        .trim());
+    const columns = [];
+    for (const token of tokens) {
+        if (token.length === 0)
+            return null;
+        if (/^"(?:[^"]|"")*"$/.test(token)) {
+            // Quoted identifier: unquote and unescape doubled quotes.
+            columns.push(token.slice(1, -1).replace(/""/g, '"'));
+        }
+        else if (/^[A-Za-z_][A-Za-z0-9_$]*$/.test(token)) {
+            columns.push(token);
+        }
+        else {
+            // Expression column (function call, operator, cast, and the like): never a plain FK.
+            return null;
+        }
+    }
+    return columns.length > 0 ? columns : null;
+}
+/**
+ * Assemble, per table, every column set that EXACTLY guarantees at-most-one row:
+ * the primary key, every UNIQUE constraint, and every PLAIN (non-partial,
+ * non-expression) UNIQUE index. Consumed by
+ * {@link buildRelationsFromForeignKeys} to flip a child relation whose FK column
+ * set matches one of these sets from `hasMany` to `hasOne` (F2, Prisma
+ * one-to-one parity).
+ */
+export function detectUniqueForeignKeySets(pkByTable, uniqueByTable, indexesByTable) {
+    const result = new Map();
+    const add = (table, cols) => {
+        if (cols.length === 0)
+            return;
+        if (!result.has(table))
+            result.set(table, []);
+        result.get(table).push(cols);
+    };
+    for (const [table, pk] of pkByTable)
+        add(table, pk);
+    for (const [table, sets] of uniqueByTable)
+        for (const cols of sets)
+            add(table, cols);
+    for (const [table, indexes] of indexesByTable) {
+        for (const idx of indexes) {
+            if (!idx.unique)
+                continue;
+            const cols = parsePlainUniqueIndexColumns(idx.definition);
+            if (cols)
+                add(table, cols);
+        }
+    }
+    return result;
+}
 /**
  * Resolve a derived relation name against the names already taken on the
  * table (scalar column fields + previously assigned relations). On collision,
@@ -583,8 +732,16 @@ function resolveRelationNameCollision(candidate, taken, table, source) {
  *   guarantee relations never shadow concrete-typed scalar columns.
  * @param unknownTypedFieldsByTable subset of the column fields whose tsType is
  *   `unknown` (json/jsonb) — legacy shadows of these are preserved (rule 2).
+ * @param uniqueSetsByTable when provided (F2), the child-table column sets that
+ *   guarantee at-most-one row (PK + unique constraints + plain unique indexes,
+ *   from {@link detectUniqueForeignKeySets}). A reverse relation whose FK column
+ *   set EXACTLY matches one of the child's unique sets is emitted as `hasOne`
+ *   (to-one) instead of `hasMany`, and named with the SINGULAR of the child
+ *   table (falling back to the legacy plural name on collision). Omit it (the
+ *   engine introspectors and `defineSchema` path do) to keep every reverse
+ *   relation `hasMany`.
  */
-export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable) {
+export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable, uniqueSetsByTable) {
     // Count FKs per (source, target) pair for disambiguation.
     const fkCounts = new Map();
     for (const fk of foreignKeys) {
@@ -673,26 +830,41 @@ export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable,
             referenceKey,
             ...actionFields,
         };
-        // --- hasMany on the target (parent) table ---
-        // e.g. posts.user_id → users.id creates users.posts (hasMany)
-        const legacyHasMany = needsDisambiguation
+        // --- reverse relation on the target (parent) table ---
+        // e.g. posts.user_id → users.id creates users.posts (hasMany), UNLESS the
+        // child's FK column set is exactly covered by a unique constraint / plain
+        // unique index (F2), then it is a one-to-one, emitted as `hasOne` and
+        // named with the SINGULAR of the child table.
+        const isUniqueFk = (uniqueSetsByTable?.get(fk.sourceTable) ?? []).some((set) => columnSetsEqual(set, fk.sourceColumns));
+        const disambSuffix = needsDisambiguation
+            ? singleColumn
+                ? `By${upperFirst(relationNameFromColumn(fk.sourceColumns[0]))}`
+                : `By${upperFirst(snakeToCamel(constraintBase))}`
+            : '';
+        const legacyReverse = needsDisambiguation
             ? singleColumn
                 ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
                 : snakeToCamel(`${fk.sourceTable}_by_${constraintBase}`)
             : snakeToCamel(fk.sourceTable);
-        const modernHasMany = needsDisambiguation
-            ? singleColumn
-                ? `${snakeToCamel(fk.sourceTable)}By${upperFirst(relationNameFromColumn(fk.sourceColumns[0]))}`
-                : `${snakeToCamel(fk.sourceTable)}By${upperFirst(snakeToCamel(constraintBase))}`
-            : null;
-        const hasManyName = resolveName(legacyHasMany, modernHasMany, fk.targetTable, `FK ${fk.constraintName}`);
-        takenFor(fk.targetTable).add(hasManyName);
-        assignedFor(fk.targetTable).add(hasManyName);
+        const modernReverse = needsDisambiguation ? `${snakeToCamel(fk.sourceTable)}${disambSuffix}` : null;
+        let reverseName;
+        const reverseType = isUniqueFk ? 'hasOne' : 'hasMany';
+        if (isUniqueFk) {
+            // Prefer the singular child-table name; fall back to the legacy plural
+            // (which stays byte-stable for any app that was on the pre-flip shape).
+            const singularReverse = `${singularize(snakeToCamel(fk.sourceTable))}${disambSuffix}`;
+            reverseName = resolveName(singularReverse, legacyReverse, fk.targetTable, `FK ${fk.constraintName}`);
+        }
+        else {
+            reverseName = resolveName(legacyReverse, modernReverse, fk.targetTable, `FK ${fk.constraintName}`);
+        }
+        takenFor(fk.targetTable).add(reverseName);
+        assignedFor(fk.targetTable).add(reverseName);
         if (!relationsByTable.has(fk.targetTable))
             relationsByTable.set(fk.targetTable, {});
-        relationsByTable.get(fk.targetTable)[hasManyName] = {
-            type: 'hasMany',
-            name: hasManyName,
+        relationsByTable.get(fk.targetTable)[reverseName] = {
+            type: reverseType,
+            name: reverseName,
             from: fk.targetTable,
             to: fk.sourceTable,
             foreignKey,

package/dist/mssql.js

@@ -92,7 +92,7 @@
 import { TurbineClient } from './client.js';
 import { postgresDialect, } from './dialect.js';
 import { ConnectionError, RelationError, UnsupportedFeatureError, ValidationError } from './errors.js';
-import { deriveEngineRelations } from './introspect.js';
+import { applyTableFilters, deriveEngineRelations } from './introspect.js';
 import importOptionalPeer from './optional-peer-import.cjs';
 import { camelToSnake, isDateType, normalizeKeyColumns, snakeToCamel, } from './schema.js';
 // ---------------------------------------------------------------------------
@@ -549,7 +549,12 @@ export const mssqlDialect = {
             .map((row) => `(${row.map(() => this.paramPlaceholder(++n)).join(', ')})`)
             .join(', ');
         const out = mssqlOutput(input.returning, 'INSERTED');
-        // skipDuplicates has no single-statement equivalent here; ignored (documented).
+        // SQL Server has no single-statement skip-duplicates form (no ON CONFLICT /
+        // INSERT IGNORE), so silently dropping the flag would let duplicate rows
+        // through against the caller's intent. Refuse loudly instead.
+        if (input.skipDuplicates) {
+            throw new UnsupportedFeatureError('createMany({ skipDuplicates: true })', 'mssql', 'SQL Server has no ON CONFLICT DO NOTHING equivalent, pre-filter conflicting rows or use a MERGE.');
+        }
         return {
             sql: `INSERT INTO ${input.table} (${input.columns.join(', ')})${out} VALUES ${placeholders}`,
             params: input.rowValues.flat(),
@@ -923,15 +928,9 @@ function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, colum
  */
 export async function introspectMssqlWith(exec, schema = 'dbo', options = {}) {
     // ----- Tables -----
-    let tableNames = (await exec("SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = @p1 AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME", [schema])).map((r) => String(r.TABLE_NAME));
-    if (options.include?.length) {
-        const inc = new Set(options.include);
-        tableNames = tableNames.filter((t) => inc.has(t));
-    }
-    if (options.exclude?.length) {
-        const exc = new Set(options.exclude);
-        tableNames = tableNames.filter((t) => !exc.has(t));
-    }
+    const candidateTables = (await exec("SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = @p1 AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME", [schema])).map((r) => String(r.TABLE_NAME));
+    // include / exclude + default bookkeeping-table exclusions (F12).
+    const tableNames = applyTableFilters(candidateTables, options);
     const tableSet = new Set(tableNames);
     // ----- Identity columns (mark hasDefault) -----
     const identityRows = await exec(`SELECT t.name AS TABLE_NAME, c.name AS COLUMN_NAME

package/dist/mysql.js

@@ -65,7 +65,7 @@
 import { TurbineClient } from './client.js';
 import { postgresDialect, } from './dialect.js';
 import { ConnectionError, UnsupportedFeatureError } from './errors.js';
-import { deriveEngineRelations } from './introspect.js';
+import { applyTableFilters, deriveEngineRelations } from './introspect.js';
 import importOptionalPeer from './optional-peer-import.cjs';
 import { isDateType, snakeToCamel, } from './schema.js';
 // ---------------------------------------------------------------------------
@@ -585,15 +585,9 @@ function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, colum
  */
 export async function introspectMysqlWith(exec, schema, options = {}) {
     // ----- Tables -----
-    let tableNames = (await exec("SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = :p1 AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME", [schema])).map((r) => String(r.TABLE_NAME));
-    if (options.include?.length) {
-        const inc = new Set(options.include);
-        tableNames = tableNames.filter((t) => inc.has(t));
-    }
-    if (options.exclude?.length) {
-        const exc = new Set(options.exclude);
-        tableNames = tableNames.filter((t) => !exc.has(t));
-    }
+    const candidateTables = (await exec("SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = :p1 AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME", [schema])).map((r) => String(r.TABLE_NAME));
+    // include / exclude + default bookkeeping-table exclusions (F12).
+    const tableNames = applyTableFilters(candidateTables, options);
     const tableSet = new Set(tableNames);
     // ----- Columns -----
     const columnRows = (await exec(`SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY,

package/dist/powdb-introspect.js

@@ -54,6 +54,7 @@
  * funnel to construct a PowDB client instead of a `pg` client for `powdb://`.
  */
 import { ValidationError } from './errors.js';
+import { applyTableFilters } from './introspect.js';
 import { quotePowqlIdent, requireCapability } from './powdb.js';
 import { snakeToCamel } from './schema.js';
 /** Coerce a wire cell to string (legacy wire cells are strings; native cells may be typed). */
@@ -107,24 +108,18 @@ export async function introspectPowdbDatabase(exec, options = {}) {
     }
     // ----- Types (one row per table, columns `name`, `columns`) -----
     const schemaRows = (await exec('schema')).rows;
-    let tableNames = schemaRows.map((r) => asString(r.name)).filter((n) => n.length > 0);
+    const candidateTables = schemaRows.map((r) => asString(r.name)).filter((n) => n.length > 0);
     // A mis-shaped `exec` (e.g. the raw client's positional `string[][]` rows
     // passed straight through) yields rows whose `name` cell is `undefined`, so
     // every table filters out and the schema comes back silently empty. Refuse
     // that instead of losing data: real rows must carry a `name`.
-    if (schemaRows.length > 0 && tableNames.length === 0) {
+    if (schemaRows.length > 0 && candidateTables.length === 0) {
         throw new ValidationError(`[turbine] PowDB introspection: the \`schema\` statement returned ${schemaRows.length} row(s) but none carried a ` +
             '`name` cell. The `exec` you supplied likely returns POSITIONAL rows (string[][]) rather than records keyed by ' +
             'column name; zip `columns` with each row (see introspectPowdbDatabase docs).');
     }
-    if (options.include?.length) {
-        const inc = new Set(options.include);
-        tableNames = tableNames.filter((t) => inc.has(t));
-    }
-    if (options.exclude?.length) {
-        const exc = new Set(options.exclude);
-        tableNames = tableNames.filter((t) => !exc.has(t));
-    }
+    // include / exclude + default bookkeeping-table exclusions (F12).
+    const tableNames = applyTableFilters(candidateTables, options);
     const tables = {};
     for (const tableName of tableNames) {
         // `describe` needs the table name in bare-identifier position → quote it so

package/dist/powql.js

@@ -38,6 +38,7 @@ import { randomUUID } from 'node:crypto';
 import { NotFoundError, ReadOnlyError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
 import { ALL_POWDB_CAPABILITIES, coerceNativeValue, isJsonColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb.js';
+import { expandCompoundUniqueWhere } from './query/compound-unique.js';
 import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
 import { escapeLike } from './query/utils.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
@@ -1007,6 +1008,13 @@ export class PowqlInterface {
             .filter((line) => line.length > 0);
     }
     async findUnique(args) {
+        // Prisma compound-unique selector → column conjunction (engine parity with
+        // the SQL findUnique family; pure metadata, so this is a one-line adoption).
+        if (args.where) {
+            const expanded = expandCompoundUniqueWhere(this.meta, args.where);
+            if (expanded !== args.where)
+                args = { ...args, where: expanded };
+        }
         return this.withMiddleware('findUnique', args, async () => {
             const { rows, native, nestedPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
             if (!rows.length)
@@ -1736,6 +1744,11 @@ export class PowqlInterface {
     }
     async createMany(args) {
         return this.withMiddleware('createMany', args, async () => {
+            if (args.skipDuplicates) {
+                // PowQL's `insert … returning` has no conflict clause, so there is no
+                // faithful skip-duplicates form; refuse rather than silently insert.
+                throw new UnsupportedFeatureError('createMany({ skipDuplicates: true })', 'powdb', 'PowQL insert has no ON CONFLICT DO NOTHING equivalent, filter duplicates before inserting.');
+            }
             const inputs = args.data.map((d) => this.applyPkDefault(d));
             if (!inputs.length)
                 return [];