turbine-orm 0.29.0 → 0.30.0

package/dist/cjs/schema-metadata.js

@@ -0,0 +1,316 @@
+"use strict";
+/**
+ * turbine-orm — defineSchema() → SchemaMetadata bridge
+ *
+ * Converts a code-first {@link SchemaDef} (the output of `defineSchema()`)
+ * into the runtime {@link SchemaMetadata} shape that the query builder,
+ * `TurbineClient`, and the non-SQL engines consume — without touching a
+ * live database.
+ *
+ * Why this exists: the historical converter path (`introspect()` +
+ * `generate()`) requires a running SQL database, but code-first engines
+ * (PowDB, in-memory SQLite bootstraps, tests) only have the `SchemaDef`.
+ * `schemaDefToMetadata()` is the pure-function equivalent: its output
+ * matches what `turbine generate` would emit into `metadata.ts` for the
+ * same schema, minus the pieces only a live catalog can know (real index
+ * names, constraint names, view flags).
+ *
+ * Parity notes (ground truth = introspect.ts + generate.ts):
+ *   - Relations are derived from `references:` exactly like introspection
+ *     derives them from foreign keys: a `belongsTo` on the child table and
+ *     a `hasMany` on the parent, with the same disambiguation rules when
+ *     multiple FKs point at the same target.
+ *   - Pure junction tables (2-column composite PK that IS the two
+ *     single-column FKs to two distinct tables, no payload columns) get
+ *     the same conservative auto-`manyToMany` treatment as introspection.
+ *   - Explicit `manyToMany` declarations on the SchemaDef are merged via
+ *     {@link applyManyToManyRelations} (additive, never clobbering).
+ *   - `indexes` is always `[]` — SchemaDef cannot express indexes, and an
+ *     empty list keeps `schemaHasIndexInfo()` false so the index advisor
+ *     and the dev-mode missing-index warning stay silent instead of
+ *     producing blanket false positives.
+ *
+ * @example
+ * ```ts
+ * import { defineSchema, schemaDefToMetadata } from 'turbine-orm';
+ *
+ * const def = defineSchema({
+ *   users: { id: { type: 'serial', primaryKey: true }, name: { type: 'text', notNull: true } },
+ *   posts: { id: { type: 'serial', primaryKey: true },
+ *            userId: { type: 'integer', notNull: true, references: 'users.id' } },
+ * });
+ * const metadata = schemaDefToMetadata(def);
+ * // → usable anywhere SchemaMetadata is expected (e.g. turbinePowDB, TurbineClient)
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemaDefToMetadata = schemaDefToMetadata;
+const introspect_js_1 = require("./introspect.js");
+const schema_js_1 = require("./schema.js");
+const schema_builder_js_1 = require("./schema-builder.js");
+// ---------------------------------------------------------------------------
+// DDL type → Postgres udt_name (what introspection reads from the catalog)
+// ---------------------------------------------------------------------------
+const DDL_TO_UDT = {
+    SERIAL: 'int4',
+    BIGSERIAL: 'int8',
+    BIGINT: 'int8',
+    INTEGER: 'int4',
+    SMALLINT: 'int2',
+    TEXT: 'text',
+    VARCHAR: 'varchar',
+    BOOLEAN: 'bool',
+    TIMESTAMPTZ: 'timestamptz',
+    DATE: 'date',
+    JSONB: 'jsonb',
+    UUID: 'uuid',
+    REAL: 'float4',
+    'DOUBLE PRECISION': 'float8',
+    NUMERIC: 'numeric',
+    BYTEA: 'bytea',
+};
+/** Resolve a ColumnConfig's Postgres base type name (udt_name form). */
+function udtName(config) {
+    if (config.type === 'ENUM')
+        return config.enumName ?? 'text';
+    if (config.type === 'VECTOR')
+        return 'vector';
+    return DDL_TO_UDT[config.type];
+}
+/** Server-generated (sequence-backed) types — pg's `nextval(...)` default. */
+function isSerialType(type) {
+    return type === 'SERIAL' || type === 'BIGSERIAL';
+}
+/**
+ * Resolve the raw column part of a `references: 'table.column'` target to a
+ * snake_case column name — accepting either the camelCase field name or the
+ * snake_case DDL name, mirroring how schema-sql.ts accepts both table forms.
+ */
+function resolveColumnName(raw, target) {
+    if (target) {
+        const viaField = target.fieldToColumn.get(raw);
+        if (viaField !== undefined)
+            return viaField;
+        if (target.columnNames.has(raw))
+            return raw;
+    }
+    return (0, schema_js_1.camelToSnake)(raw);
+}
+// ---------------------------------------------------------------------------
+// The converter
+// ---------------------------------------------------------------------------
+/**
+ * Convert a code-first {@link SchemaDef} into runtime {@link SchemaMetadata}.
+ *
+ * Pure function — no database connection, no side effects, input untouched.
+ * The output is shaped identically to the `SCHEMA` constant `turbine generate`
+ * emits from introspection, so it can be handed to any consumer that expects
+ * introspected metadata: `new TurbineClient(config, metadata)`,
+ * `turbinePowDB(..., metadata)`, `QueryInterface`, the index advisor, etc.
+ *
+ * What maps:
+ *   - Columns → full {@link ColumnMetadata} (snake_case name, camelCase field,
+ *     pg type names, TS types, nullability, defaults, `isGenerated` for
+ *     serial/bigserial, array + varchar length info, date-column tracking).
+ *   - Column-level `primaryKey` and table-level composite `primaryKey`.
+ *   - `unique: true` columns → single-column `uniqueColumns` entries.
+ *   - `references:` FKs → `belongsTo` (child) + `hasMany` (parent) relations,
+ *     including `onDelete`/`onUpdate` actions (the `'no action'` default is
+ *     omitted, matching introspection).
+ *   - Pure junction tables → auto-detected `manyToMany` relations (same
+ *     conservative rules as introspection).
+ *   - Explicit `manyToMany` declarations → merged additively.
+ *   - Schema-level `enums`.
+ *
+ * What SchemaDef cannot express (and how it degrades):
+ *   - Indexes → every table gets `indexes: []`, which keeps
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no
+ *     false positives on code-first metadata.
+ *   - Views → never marked (`isView` is introspection-only).
+ *   - Composite foreign keys → `references:` is single-column by design.
+ */
+function schemaDefToMetadata(def) {
+    // ----- Pass 1: resolve every table's snake_case names for FK lookups -----
+    // Lookup accepts the accessor key (camelCase), the DDL name (snake_case),
+    // and the explicit `accessor` field — same tolerance as schema-sql.ts.
+    const lookup = new Map();
+    for (const [key, tableDef] of Object.entries(def.tables)) {
+        const fieldToColumn = new Map();
+        const columnNames = new Set();
+        for (const field of Object.keys(tableDef.columns)) {
+            const snake = (0, schema_js_1.camelToSnake)(field);
+            fieldToColumn.set(field, snake);
+            columnNames.add(snake);
+        }
+        const resolved = { name: tableDef.name, fieldToColumn, columnNames };
+        lookup.set(key, resolved);
+        if (tableDef.name)
+            lookup.set(tableDef.name, resolved);
+        if (tableDef.accessor)
+            lookup.set(tableDef.accessor, resolved);
+    }
+    // ----- Pass 2: collect resolved single-column FKs -----
+    const foreignKeys = [];
+    for (const tableDef of Object.values(def.tables)) {
+        for (const [field, config] of Object.entries(tableDef.columns)) {
+            if (!config.referencesTarget)
+                continue;
+            const parts = config.referencesTarget.split('.');
+            if (parts.length !== 2)
+                continue;
+            const target = lookup.get(parts[0]);
+            // Reference to a table outside this SchemaDef — skip, exactly like
+            // introspection skips FKs whose target is excluded from the table set.
+            if (!target)
+                continue;
+            foreignKeys.push({
+                sourceTable: tableDef.name,
+                sourceColumn: (0, schema_js_1.camelToSnake)(field),
+                targetTable: target.name,
+                targetColumn: resolveColumnName(parts[1], target),
+                onDelete: config.onDelete ?? undefined,
+                onUpdate: config.onUpdate ?? undefined,
+            });
+        }
+    }
+    // ----- Pass 3: derive belongsTo / hasMany relations (SHARED with introspect)
+    //
+    // Delegates to the exact same builder introspection uses
+    // (`buildRelationsFromForeignKeys`), so the same logical schema yields
+    // IDENTICAL relation names whether it arrives via `defineSchema()` or a live
+    // catalog: legacy-first naming, per-column disambiguation for several FKs to
+    // the same target, and collision resolution against scalar column fields
+    // (json/jsonb `unknown`-typed shadows keep the historical name). The old
+    // local reimplementation had NO collision guard — `posts.user` (text) +
+    // `userId references users.id` produced a relation `user` that shadowed the
+    // scalar, and two FKs deriving the same name silently clobbered each other
+    // (N-4).
+    //
+    // Constraint names are synthesized in pg's default `<table>_<column>_fkey`
+    // form; they only feed the referential-action lookup and composite-FK
+    // naming (never hit here — `references:` is single-column by design).
+    const fkEntries = [];
+    const fkActions = new Map();
+    for (const fk of foreignKeys) {
+        const constraintName = `${fk.sourceTable}_${fk.sourceColumn}_fkey`;
+        fkEntries.push({
+            sourceTable: fk.sourceTable,
+            sourceColumns: [fk.sourceColumn],
+            targetTable: fk.targetTable,
+            targetColumns: [fk.targetColumn],
+            constraintName,
+        });
+        fkActions.set(constraintName, {
+            onDelete: fk.onDelete ?? 'no action',
+            onUpdate: fk.onUpdate ?? 'no action',
+        });
+    }
+    // Taken-name seeds: every table's camelCase column fields (the SchemaDef
+    // keys ARE the fields) + which of them are json/jsonb (`unknown`-typed).
+    const columnFieldsByTable = new Map();
+    const unknownTypedFieldsByTable = new Map();
+    for (const tableDef of Object.values(def.tables)) {
+        const fields = Object.keys(tableDef.columns);
+        columnFieldsByTable.set(tableDef.name, new Set(fields));
+        // ENUM columns map to concrete union types in the generated layer, so
+        // only genuine json/jsonb (`unknown`-typed) columns qualify as shadows.
+        unknownTypedFieldsByTable.set(tableDef.name, new Set(fields.filter((f) => {
+            const config = tableDef.columns[f];
+            if (config.type === 'ENUM')
+                return false;
+            const wire = config.isArray ? `_${udtName(config)}` : udtName(config);
+            return (0, introspect_js_1.isUnknownTsType)((0, schema_js_1.pgTypeToTs)(wire, false));
+        })));
+    }
+    const relationsByTable = (0, introspect_js_1.buildRelationsFromForeignKeys)(fkEntries, columnFieldsByTable, fkActions, unknownTypedFieldsByTable);
+    // ----- Pass 4: conservative junction auto-m2m (SHARED with introspect) ---
+    // Same shared detector + naming/collision rules as introspection: a table J
+    // is a PURE junction only when its PK is exactly the two single-column FKs
+    // to two DISTINCT tables and it has no payload columns.
+    const pkByTable = new Map();
+    const columnNamesByTable = new Map();
+    for (const tableDef of Object.values(def.tables)) {
+        const pkFields = tableDef.primaryKey && tableDef.primaryKey.length > 0
+            ? [...tableDef.primaryKey]
+            : Object.entries(tableDef.columns)
+                .filter(([, c]) => c.isPrimaryKey)
+                .map(([f]) => f);
+        pkByTable.set(tableDef.name, pkFields.map(schema_js_1.camelToSnake));
+        columnNamesByTable.set(tableDef.name, Object.keys(tableDef.columns).map(schema_js_1.camelToSnake));
+    }
+    (0, introspect_js_1.addAutoManyToManyRelations)(Object.values(def.tables).map((t) => t.name), fkEntries, pkByTable, columnNamesByTable, relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable);
+    // ----- Pass 5: assemble TableMetadata -----
+    const tables = {};
+    for (const tableDef of Object.values(def.tables)) {
+        const columns = [];
+        const columnMap = {};
+        const reverseColumnMap = {};
+        const dateColumns = new Set();
+        const dialectTypes = {};
+        const pgTypes = {};
+        const allColumns = [];
+        const primaryKey = [];
+        const uniqueColumns = [];
+        for (const [field, config] of Object.entries(tableDef.columns)) {
+            const name = (0, schema_js_1.camelToSnake)(field);
+            const base = udtName(config);
+            // Introspection reports array columns with pg's leading-underscore
+            // udt_name (`_text`), which pgTypeToTs also understands.
+            const wireType = config.isArray ? `_${base}` : base;
+            const serial = isSerialType(config.type);
+            // PK members and serials are NOT NULL in Postgres regardless of flags.
+            const nullable = !(config.isPrimaryKey || config.isNotNull || serial);
+            const col = {
+                name,
+                field,
+                dialectType: wireType,
+                pgType: wireType,
+                tsType: (0, schema_js_1.pgTypeToTs)(wireType, nullable),
+                nullable,
+                hasDefault: config.defaultValue != null || serial,
+                isArray: config.isArray,
+                arrayType: (0, schema_js_1.pgArrayType)(base),
+                pgArrayType: (0, schema_js_1.pgArrayType)(base),
+                ...(serial ? { isGenerated: true } : {}),
+                ...(config.maxLength != null ? { maxLength: config.maxLength } : {}),
+            };
+            columns.push(col);
+            columnMap[field] = name;
+            reverseColumnMap[name] = field;
+            allColumns.push(name);
+            dialectTypes[name] = wireType;
+            pgTypes[name] = wireType;
+            if ((0, schema_js_1.isDateType)(base))
+                dateColumns.add(name);
+            if (config.isPrimaryKey)
+                primaryKey.push(name);
+            if (config.isUnique)
+                uniqueColumns.push([name]);
+        }
+        // Table-level composite PK takes precedence (defineSchema already cleared
+        // the column-level flags for its members).
+        const pk = tableDef.primaryKey && tableDef.primaryKey.length > 0 ? tableDef.primaryKey.map(schema_js_1.camelToSnake) : primaryKey;
+        tables[tableDef.name] = {
+            name: tableDef.name,
+            columns,
+            columnMap,
+            reverseColumnMap,
+            dateColumns,
+            dialectTypes,
+            pgTypes,
+            allColumns,
+            primaryKey: pk,
+            uniqueColumns,
+            relations: relationsByTable.get(tableDef.name) ?? {},
+            // SchemaDef cannot express indexes. An empty list keeps
+            // schemaHasIndexInfo() false → no index-advisor false positives.
+            indexes: [],
+        };
+    }
+    const enums = {};
+    for (const [name, labels] of Object.entries(def.enums ?? {})) {
+        enums[name] = [...labels];
+    }
+    // ----- Pass 6: merge explicit manyToMany declarations (additive) ---------
+    return (0, schema_builder_js_1.applyManyToManyRelations)({ tables, enums }, def);
+}

package/dist/cjs/sqlite.js

@@ -56,6 +56,7 @@ const node_module_1 = require("node:module");
 const client_js_1 = require("./client.js");
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
+const introspect_js_1 = require("./introspect.js");
 const schema_js_1 = require("./schema.js");
 let cachedDatabaseSync;
 /**
@@ -645,95 +646,13 @@ function introspectSqliteDatabase(db, options = {}) {
         indexesByTable.set(tableName, idxMeta);
         uniqueByTable.set(tableName, uniques);
     }
-    // ----- Build relations from foreign keys (belongsTo + hasMany) -----
-    const fkCounts = new Map();
-    for (const fk of foreignKeys) {
-        const key = `${fk.sourceTable}->${fk.targetTable}`;
-        fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
-    }
-    const relationsByTable = new Map();
-    for (const fk of foreignKeys) {
-        const needsDisambiguation = (fkCounts.get(`${fk.sourceTable}->${fk.targetTable}`) ?? 0) > 1;
-        const foreignKey = fk.sourceColumns.length === 1 ? fk.sourceColumns[0] : fk.sourceColumns;
-        const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
-        const belongsToName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? (0, schema_js_1.snakeToCamel)(fk.sourceColumns[0].replace(/_id$/, ''))
-            : (0, schema_js_1.singularize)((0, schema_js_1.snakeToCamel)(fk.targetTable));
-        if (!relationsByTable.has(fk.sourceTable))
-            relationsByTable.set(fk.sourceTable, {});
-        relationsByTable.get(fk.sourceTable)[belongsToName] = {
-            type: 'belongsTo',
-            name: belongsToName,
-            from: fk.sourceTable,
-            to: fk.targetTable,
-            foreignKey,
-            referenceKey,
-        };
-        const hasManyName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? (0, schema_js_1.snakeToCamel)(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
-            : (0, schema_js_1.snakeToCamel)(fk.sourceTable);
-        if (!relationsByTable.has(fk.targetTable))
-            relationsByTable.set(fk.targetTable, {});
-        relationsByTable.get(fk.targetTable)[hasManyName] = {
-            type: 'hasMany',
-            name: hasManyName,
-            from: fk.targetTable,
-            to: fk.sourceTable,
-            foreignKey,
-            referenceKey,
-        };
-    }
-    // ----- Conservative many-to-many auto-detection (additive) -----
-    // A table J is a pure junction iff: PK is exactly two columns, exactly two
-    // single-column FKs whose source columns ARE the PK, two distinct target
-    // tables, and no payload columns. Mirrors the Postgres introspector.
-    for (const tableName of tableNames) {
-        const pk = pkByTable.get(tableName) ?? [];
-        if (pk.length !== 2)
-            continue;
-        const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
-        if (tableFks.length !== 2)
-            continue;
-        if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
-            continue;
-        const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
-        const pkSet = new Set(pk);
-        if (!fkCols.every((c) => pkSet.has(c)))
-            continue;
-        if (new Set(fkCols).size !== 2)
-            continue;
-        const [fkA, fkB] = tableFks;
-        if (fkA.targetTable === fkB.targetTable)
-            continue;
-        const jCols = (columnsByTable.get(tableName) ?? []).map((c) => c.name);
-        if (jCols.length !== 2)
-            continue;
-        const addM2M = (self, other) => {
-            const sourceTbl = self.targetTable;
-            const targetTbl = other.targetTable;
-            const relName = (0, schema_js_1.snakeToCamel)(targetTbl);
-            if (!relationsByTable.has(sourceTbl))
-                relationsByTable.set(sourceTbl, {});
-            const existing = relationsByTable.get(sourceTbl);
-            if (existing[relName])
-                return;
-            existing[relName] = {
-                type: 'manyToMany',
-                name: relName,
-                from: sourceTbl,
-                to: targetTbl,
-                referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                through: {
-                    table: tableName,
-                    sourceKey: self.sourceColumns[0],
-                    targetKey: other.sourceColumns[0],
-                },
-            };
-        };
-        addM2M(fkA, fkB);
-        addM2M(fkB, fkA);
-    }
+    // ----- Build relations from foreign keys (belongsTo + hasMany + m2m) -----
+    // Delegated to the SHARED introspection pipeline (introspect.ts) so SQLite
+    // derives IDENTICAL relation names to the Postgres introspector for the
+    // same logical schema — legacy-first naming, per-column disambiguation,
+    // collision resolution against scalar column fields, and the conservative
+    // pure-junction manyToMany auto-detection included.
+    const relationsByTable = (0, introspect_js_1.deriveEngineRelations)(tableNames, foreignKeys, pkByTable, columnsByTable);
     // ----- Assemble TableMetadata -----
     const tables = {};
     for (const tableName of tableNames) {

package/dist/cli/index.d.ts

@@ -44,6 +44,8 @@ export interface CliArgs {
     fix?: boolean;
     zod?: boolean;
     includeViews?: boolean;
+    /** Omit the `Generated at:` header line for reproducible (diff-stable) output. */
+    noTimestamp?: boolean;
     port?: number;
     host?: string;
     noOpen?: boolean;

package/dist/cli/index.js

@@ -102,6 +102,9 @@ export function parseArgs(argv = process.argv.slice(2)) {
             case '--include-views':
                 result.includeViews = true;
                 break;
+            case '--no-timestamp':
+                result.noTimestamp = true;
+                break;
             case '--allow-destructive':
                 result.allowDestructive = true;
                 break;
@@ -518,6 +521,7 @@ async function cmdGenerate(args, config) {
         outDir: config.out,
         connectionString: url,
         zod: args.zod,
+        noTimestamp: args.noTimestamp,
     });
     genSpinner.succeed(`Generated ${bold(String(result.files.length))} files in ${elapsed(startTime)}`);
     // List files
@@ -1464,6 +1468,7 @@ function showGenerateHelp() {
     console.log(`    ${cyan('--exclude')} ${dim('<tables>')}    Comma-separated tables to exclude`);
     console.log(`    ${cyan('--zod')}                 Also emit ${cyan('zod.ts')} validation schemas ${dim('(needs the zod dep)')}`);
     console.log(`    ${cyan('--include-views')}       Include views + materialized views as read-only entities`);
+    console.log(`    ${cyan('--no-timestamp')}        Omit the ${dim('Generated at:')} header line ${dim('(reproducible, diff-stable output)')}`);
     console.log(`    ${cyan('--allow-empty')}         Generate even when introspection matches 0 tables`);
     newline();
 }

package/dist/cli/mcp.d.ts

@@ -1,4 +1,5 @@
 import type { Readable, Writable } from 'node:stream';
+import { type ColumnMetadata, type RelationDef } from '../schema.js';
 export interface McpServerOptions {
     url: string;
     schema: string;
@@ -14,4 +15,21 @@ export interface McpServerHandle {
     dispose(): Promise<void>;
 }
 export declare function startMcpServer(options: McpServerOptions, transport?: McpTransport): McpServerHandle;
+interface ForeignKeyRow {
+    source_table: string;
+    source_column: string;
+    target_table: string;
+    target_column: string;
+    constraint_name: string;
+}
+/**
+ * Group raw FK rows into constraint-level entries and delegate relation
+ * naming to the SHARED introspection builder (`buildRelationsFromForeignKeys`
+ * + `addAutoManyToManyRelations` in ../introspect.ts). MCP previously carried
+ * a stale copy of a retired naming scheme, so `turbine mcp` and `turbine
+ * generate` derived DIFFERENT relation names from the same database (N-3).
+ * Exported for the parity unit test.
+ */
+export declare function buildRelations(tableNames: string[], columnsByTable: Map<string, ColumnMetadata[]>, pkByTable: Map<string, string[]>, rows: ForeignKeyRow[], enums?: Record<string, string[]>): Map<string, Record<string, RelationDef>>;
 export declare function runMcpServer(options: McpServerOptions): Promise<void>;
+export {};

package/dist/cli/mcp.js

@@ -3,8 +3,9 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import pg from 'pg';
 import { findMissingRelationIndexes } from '../index-advisor.js';
+import { addAutoManyToManyRelations, buildRelationsFromForeignKeys, isUnknownTsType, } from '../introspect.js';
 import { QueryInterface, quoteIdent } from '../query/index.js';
-import { isDateType, pgArrayType, pgTypeToTs, singularize, snakeToCamel, } from '../schema.js';
+import { isDateType, pgArrayType, pgTypeToTs, snakeToCamel, } from '../schema.js';
 import { listMigrationFiles } from './migrate.js';
 /**
  * Walk up from the running script to find turbine-orm's own package.json.
@@ -550,7 +551,7 @@ async function loadSchemaMetadata(client, options) {
         labels.push(row.enumlabel);
         enums[row.typname] = labels;
     }
-    const relationsByTable = buildRelations(tableNames, columnsByTable, pkByTable, fkResult.rows);
+    const relationsByTable = buildRelations(tableNames, columnsByTable, pkByTable, fkResult.rows, enums);
     const tables = {};
     for (const tableName of tableNames) {
         const columns = columnsByTable.get(tableName) ?? [];
@@ -589,7 +590,15 @@ async function loadSchemaMetadata(client, options) {
     }
     return { tables, enums };
 }
-function buildRelations(tableNames, columnsByTable, pkByTable, rows) {
+/**
+ * Group raw FK rows into constraint-level entries and delegate relation
+ * naming to the SHARED introspection builder (`buildRelationsFromForeignKeys`
+ * + `addAutoManyToManyRelations` in ../introspect.ts). MCP previously carried
+ * a stale copy of a retired naming scheme, so `turbine mcp` and `turbine
+ * generate` derived DIFFERENT relation names from the same database (N-3).
+ * Exported for the parity unit test.
+ */
+export function buildRelations(tableNames, columnsByTable, pkByTable, rows, enums = {}) {
     const tableSet = new Set(tableNames);
     const groups = new Map();
     for (const row of rows) {
@@ -607,95 +616,18 @@ function buildRelations(tableNames, columnsByTable, pkByTable, rows) {
         groups.set(row.constraint_name, group);
     }
     const foreignKeys = [...groups.values()];
-    const fkCounts = new Map();
-    for (const fk of foreignKeys) {
-        const key = `${fk.sourceTable}→${fk.targetTable}`;
-        fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
-    }
-    const relations = new Map();
-    for (const fk of foreignKeys) {
-        const pairKey = `${fk.sourceTable}→${fk.targetTable}`;
-        const needsDisambiguation = (fkCounts.get(pairKey) ?? 0) > 1;
-        const foreignKey = oneOrMany(fk.sourceColumns);
-        const referenceKey = oneOrMany(fk.targetColumns);
-        const belongsToName = needsDisambiguation
-            ? fk.sourceColumns.length === 1
-                ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
-                : snakeToCamel(fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, ''))
-            : singularize(snakeToCamel(fk.targetTable));
-        const hasManyName = needsDisambiguation
-            ? fk.sourceColumns.length === 1
-                ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
-                : snakeToCamel(`${fk.sourceTable}_by_${fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, '')}`)
-            : snakeToCamel(fk.sourceTable);
-        const sourceRels = relations.get(fk.sourceTable) ?? {};
-        sourceRels[belongsToName] = {
-            type: 'belongsTo',
-            name: belongsToName,
-            from: fk.sourceTable,
-            to: fk.targetTable,
-            foreignKey,
-            referenceKey,
-        };
-        relations.set(fk.sourceTable, sourceRels);
-        const targetRels = relations.get(fk.targetTable) ?? {};
-        targetRels[hasManyName] = {
-            type: 'hasMany',
-            name: hasManyName,
-            from: fk.targetTable,
-            to: fk.sourceTable,
-            foreignKey,
-            referenceKey,
-        };
-        relations.set(fk.targetTable, targetRels);
-    }
-    addManyToManyRelations(tableNames, columnsByTable, pkByTable, foreignKeys, relations);
+    const columnFieldsByTable = new Map();
+    const unknownTypedFieldsByTable = new Map();
+    for (const [tbl, cols] of columnsByTable) {
+        columnFieldsByTable.set(tbl, new Set(cols.map((c) => c.field)));
+        // Enum-typed columns also report tsType 'unknown', but the generated type
+        // layer gives them a concrete union — only json/jsonb qualify as shadows.
+        unknownTypedFieldsByTable.set(tbl, new Set(cols.filter((c) => isUnknownTsType(c.tsType) && !Object.hasOwn(enums, c.pgType)).map((c) => c.field)));
+    }
+    const relations = buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, undefined, unknownTypedFieldsByTable);
+    addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, new Map(Array.from(columnsByTable, ([tbl, cols]) => [tbl, cols.map((c) => c.name)])), relations, columnFieldsByTable, unknownTypedFieldsByTable);
     return relations;
 }
-function addManyToManyRelations(tableNames, columnsByTable, pkByTable, foreignKeys, relations) {
-    for (const tableName of tableNames) {
-        const pk = pkByTable.get(tableName) ?? [];
-        if (pk.length !== 2)
-            continue;
-        const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
-        if (tableFks.length !== 2 || tableFks.some((fk) => fk.sourceColumns.length !== 1))
-            continue;
-        const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
-        const pkSet = new Set(pk);
-        if (!fkCols.every((column) => pkSet.has(column)) || new Set(fkCols).size !== 2)
-            continue;
-        const [fkA, fkB] = tableFks;
-        if (fkA.targetTable === fkB.targetTable)
-            continue;
-        const junctionColumns = (columnsByTable.get(tableName) ?? []).map((column) => column.name);
-        if (junctionColumns.length !== 2)
-            continue;
-        addManyToManyDirection(relations, tableName, fkA, fkB);
-        addManyToManyDirection(relations, tableName, fkB, fkA);
-    }
-}
-function addManyToManyDirection(relations, junctionTable, self, other) {
-    const sourceTable = self.targetTable;
-    const targetTable = other.targetTable;
-    const relName = snakeToCamel(targetTable);
-    const tableRelations = relations.get(sourceTable) ?? {};
-    if (tableRelations[relName])
-        return;
-    tableRelations[relName] = {
-        type: 'manyToMany',
-        name: relName,
-        from: sourceTable,
-        to: targetTable,
-        referenceKey: oneOrMany(self.targetColumns),
-        foreignKey: oneOrMany(self.targetColumns),
-        through: {
-            table: junctionTable,
-            sourceKey: self.sourceColumns[0],
-            targetKey: other.sourceColumns[0],
-        },
-    };
-    relations.set(sourceTable, tableRelations);
-}
 async function estimateRows(client, schema) {
     const result = await client.query(`SELECT c.relname, c.reltuples::bigint::text AS reltuples
      FROM pg_class c
@@ -723,9 +655,6 @@ function extractIndexColumns(indexdef) {
         .replace(/ (ASC|DESC)$/i, '')
         .replace(/^"|"$/g, ''));
 }
-function oneOrMany(columns) {
-    return columns.length === 1 ? columns[0] : columns;
-}
 function optionalLimit(value) {
     if (value === undefined)
         return 50;

package/dist/client.d.ts

@@ -149,8 +149,12 @@ export interface TurbineConfig {
     logging?: boolean;
     /** Default LIMIT applied to findMany() when no limit is specified (opt-in, default: undefined) */
     defaultLimit?: number;
-    /** Log a warning when findMany() is called without a limit (default: false) */
-    warnOnUnlimited?: boolean;
+    /**
+     * Log a warning when findMany() is called without a limit (default: false).
+     * Pass a per-table map (`{ users: false }`) to override the default for
+     * specific tables; per-call `warnOnUnlimited` on findMany args wins over both.
+     */
+    warnOnUnlimited?: boolean | Record<string, boolean>;
     /**
      * Interpret Postgres `timestamp` (without time zone) values as UTC — both
      * at the driver level (OID 1114 type parser, registered only when Turbine