turbine-orm 0.29.0 → 0.31.0

package/dist/cjs/query/filters.js

@@ -7,13 +7,15 @@
  * and execution rather than filter-shape bookkeeping.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = void 0;
+exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSON_RANGE_OPERATORS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = exports.COLUMN_REF_OPERATORS = void 0;
 exports.isWhereOperator = isWhereOperator;
 exports.isUnmatchedPlainObject = isUnmatchedPlainObject;
+exports.isColumnRef = isColumnRef;
 exports.fingerprintOperatorShape = fingerprintOperatorShape;
 exports.assertBindableEqualsOperand = assertBindableEqualsOperand;
 exports.sortedKeys = sortedKeys;
 exports.sortedEntries = sortedEntries;
+exports.fingerprintJsonFilterShape = fingerprintJsonFilterShape;
 exports.isJsonFilter = isJsonFilter;
 exports.findJsonUniqueKey = findJsonUniqueKey;
 exports.isArrayFilter = isArrayFilter;
@@ -23,6 +25,7 @@ exports.validateTextSearchConfig = validateTextSearchConfig;
 exports.isVectorFilter = isVectorFilter;
 exports.isVectorOrderBy = isVectorOrderBy;
 exports.isOrderBySpec = isOrderBySpec;
+exports.isJsonPathOrderBy = isJsonPathOrderBy;
 exports.normalizeOrderBy = normalizeOrderBy;
 const errors_js_1 = require("../errors.js");
 const utils_js_1 = require("./utils.js");
@@ -55,17 +58,48 @@ function isUnmatchedPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * Operator keys that accept a {@link ColumnRef} (`{ col: 'otherField' }`)
+ * value for column-to-column comparison. `in`/`notIn` and the LIKE operators
+ * take values only.
+ */
+exports.COLUMN_REF_OPERATORS = new Set(['equals', 'not', 'gt', 'gte', 'lt', 'lte']);
+/**
+ * Check if an operator value is a column reference: a plain object whose ONLY
+ * key is `col` with a string value. Anything else (extra keys, non-string
+ * `col`) is treated as a plain value so JSON payloads that merely contain a
+ * `col` property keep their equality meaning.
+ */
+function isColumnRef(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || value instanceof Date)
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && keys[0] === 'col' && typeof value.col === 'string';
+}
 /**
  * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
  * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
  * param pushed), so null-ness is part of the shape — without it a cache entry
  * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ *
+ * Column references ({@link ColumnRef}) compile the referenced column into the
+ * SQL TEXT (no param bound), so the referenced field name is part of the shape
+ *: `{ equals: { col: 'a' } }` and `{ equals: { col: 'b' } }` must never share
+ * a cache entry. The name is JSON-encoded so exotic field names cannot collide
+ * with other fingerprint tokens.
  */
 function fingerprintOperatorShape(value) {
     const obj = value;
     const opKeys = Object.keys(obj)
         .filter((k) => k !== 'mode')
-        .map((k) => ((k === 'equals' || k === 'not') && obj[k] === null ? `${k}:null` : k))
+        .map((k) => {
+        const v = obj[k];
+        if ((k === 'equals' || k === 'not') && v === null)
+            return `${k}:null`;
+        if (exports.COLUMN_REF_OPERATORS.has(k) && isColumnRef(v))
+            return `${k}:col(${JSON.stringify(v.col)})`;
+        return k;
+    })
         .sort();
     const modeStr = value.mode === 'insensitive' ? ':i' : '';
     return `op(${opKeys.join(',')}${modeStr})`;
@@ -109,6 +143,36 @@ function sortedEntries(obj) {
 exports.UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
 /** Known JSONB operator keys */
 exports.JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
+/**
+ * JSON range comparison operators → SQL comparison tokens, in the FIXED order
+ * the build and collect paths iterate them. These keys are deliberately NOT in
+ * {@link JSONB_OPERATOR_KEYS}: `gt`/`gte`/`lt`/`lte` overlap with
+ * `WhereOperator`, so a bare `{ gt: 5 }` must keep its column-comparison
+ * meaning. They only compile as JSON range ops when the object is already a
+ * {@link JsonFilter} (detected via `path` / `equals` / `contains` / `hasKey`),
+ * and they always require `path`.
+ */
+exports.JSON_RANGE_OPERATORS = {
+    gt: '>',
+    gte: '>=',
+    lt: '<',
+    lte: '<=',
+};
+/**
+ * Value-invariant shape fingerprint for a {@link JsonFilter}. Range operators
+ * are annotated with the comparison value's kind (`#n` numeric / `#s` string)
+ * because a numeric comparison compiles to a `::numeric` cast — a different
+ * SQL text than the text comparison — so the two must never share a cached
+ * SQL entry.
+ */
+function fingerprintJsonFilterShape(filter) {
+    const obj = filter;
+    const parts = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort()
+        .map((k) => (k in exports.JSON_RANGE_OPERATORS ? `${k}#${typeof obj[k] === 'number' ? 'n' : 's'}` : k));
+    return `json(${parts.join(',')})`;
+}
 /**
  * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
  * appear in any other where-filter shape, so the presence of one of these is
@@ -238,6 +302,20 @@ function isVectorOrderBy(value) {
 function isOrderBySpec(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value) && 'sort' in value;
 }
+/**
+ * Check if an orderBy value is a JSON-path ordering: `{ path: [...] }` with an
+ * ARRAY path. The array requirement disambiguates from relation orderBy values
+ * (whose entries are directions/specs keyed by target column: a target column
+ * literally named `path` maps to a string direction, never an array), and the
+ * `distance`/`sort` exclusions keep vector and spec shapes out.
+ */
+function isJsonPathOrderBy(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    if ('distance' in value || 'sort' in value)
+        return false;
+    return Array.isArray(value.path);
+}
 /**
  * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
  * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile

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 {};