turbine-orm 0.29.0 → 0.30.0

package/README.md

@@ -882,7 +882,7 @@ Everything is honest about what ports and what doesn't. Features marked **PG-onl
 
 **Engine notes:** SQLite uses `RETURNING` (≥ 3.35) just like Postgres. MySQL has no `RETURNING`, so writes re-`SELECT` the affected row and **`createMany` returns `[]`** (the rows ARE inserted — re-query if you need them). SQL Server returns rows via `OUTPUT`/`MERGE`; `DISTINCT ON` is Postgres-only. Only Postgres streams via a true cursor (constant memory); the other engines' `findManyStream` materializes the result then yields it in batches. Optimistic locking throws `OptimisticLockError` on all engines (on MySQL the conflict is detected from the version-checked UPDATE's affected-row count). The `turbine` CLI (`generate`, `migrate`) is currently PostgreSQL-only — point the engine factories at a hand-written or programmatically introspected `SCHEMA`.
 
-**PowDB** speaks its own non-SQL query language (PowQL), so it sits outside the SQL matrix above. Writes use a trailing **`returning`** keyword (upsert reselects by PK). PKs are server-assigned `auto` ints **or** client UUIDs. Nested relations load client-side (N+1, including many-to-many via the junction — no `json_agg`). Nested writes cover hasMany/hasOne/belongsTo; many-to-many nested writes are not supported. Transactions are single-writer (no nested savepoints). Schema is code-first via `defineSchema` (no wire introspection). Embedded `syncMode: 'normal'` moves fsync off the commit path; the networked transport runs the same data over a socket. Cursor streaming and the Postgres-only trio (pgvector / LISTEN/NOTIFY / RLS session GUCs) throw `UnsupportedFeatureError`. Full details: **[turbineorm.dev/engines#powdb](https://turbineorm.dev/engines#powdb)**.
+**PowDB** speaks its own non-SQL query language (PowQL), so it sits outside the SQL matrix above. Writes use a trailing **`returning`** keyword (upsert reselects by PK). PKs are server-assigned `auto` ints **or** client UUIDs. Nested relations load client-side (N+1, including many-to-many via the junction — no `json_agg`). Nested writes cover hasMany/hasOne/belongsTo; many-to-many nested writes are not supported. Transactions are single-writer: concurrent `$transaction` calls queue FIFO (bounded by `transactionQueueTimeoutMs`); nested/re-entrant transactions throw typed errors (no savepoints). Schema is code-first via `defineSchema` (no wire introspection) — `schemaDefToMetadata()` bridges it to any engine that needs runtime metadata. Embedded `syncMode: 'normal'` moves fsync off the commit path; the networked transport runs the same data over a socket. Cursor streaming and the Postgres-only trio (pgvector / LISTEN/NOTIFY / RLS session GUCs) throw `UnsupportedFeatureError`. Full details: **[turbineorm.dev/engines#powdb](https://turbineorm.dev/engines#powdb)**.
 
 Full setup, signatures, and the complete support matrix: **[turbineorm.dev/engines](https://turbineorm.dev/engines)**.
 

package/dist/cjs/cli/index.js

@@ -141,6 +141,9 @@ 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;
@@ -557,6 +560,7 @@ async function cmdGenerate(args, config) {
         outDir: config.out,
         connectionString: url,
         zod: args.zod,
+        noTimestamp: args.noTimestamp,
     });
     genSpinner.succeed(`Generated ${(0, ui_js_1.bold)(String(result.files.length))} files in ${(0, ui_js_1.elapsed)(startTime)}`);
     // List files
@@ -1503,6 +1507,7 @@ function showGenerateHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--exclude')} ${(0, ui_js_1.dim)('<tables>')}    Comma-separated tables to exclude`);
     console.log(`    ${(0, ui_js_1.cyan)('--zod')}                 Also emit ${(0, ui_js_1.cyan)('zod.ts')} validation schemas ${(0, ui_js_1.dim)('(needs the zod dep)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--include-views')}       Include views + materialized views as read-only entities`);
+    console.log(`    ${(0, ui_js_1.cyan)('--no-timestamp')}        Omit the ${(0, ui_js_1.dim)('Generated at:')} header line ${(0, ui_js_1.dim)('(reproducible, diff-stable output)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--allow-empty')}         Generate even when introspection matches 0 tables`);
     (0, ui_js_1.newline)();
 }

package/dist/cjs/cli/mcp.js

@@ -4,12 +4,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startMcpServer = startMcpServer;
+exports.buildRelations = buildRelations;
 exports.runMcpServer = runMcpServer;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const pg_1 = __importDefault(require("pg"));
 const index_advisor_js_1 = require("../index-advisor.js");
+const introspect_js_1 = require("../introspect.js");
 const index_js_1 = require("../query/index.js");
 const schema_js_1 = require("../schema.js");
 const migrate_js_1 = require("./migrate.js");
@@ -557,7 +559,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) ?? [];
@@ -596,7 +598,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.
+ */
+function buildRelations(tableNames, columnsByTable, pkByTable, rows, enums = {}) {
     const tableSet = new Set(tableNames);
     const groups = new Map();
     for (const row of rows) {
@@ -614,95 +624,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
-                ? (0, schema_js_1.snakeToCamel)(fk.sourceColumns[0].replace(/_id$/, ''))
-                : (0, schema_js_1.snakeToCamel)(fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, ''))
-            : (0, schema_js_1.singularize)((0, schema_js_1.snakeToCamel)(fk.targetTable));
-        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}_by_${fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, '')}`)
-            : (0, schema_js_1.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) => (0, introspect_js_1.isUnknownTsType)(c.tsType) && !Object.hasOwn(enums, c.pgType)).map((c) => c.field)));
+    }
+    const relations = (0, introspect_js_1.buildRelationsFromForeignKeys)(foreignKeys, columnFieldsByTable, undefined, unknownTypedFieldsByTable);
+    (0, introspect_js_1.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 = (0, schema_js_1.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
@@ -730,9 +663,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/cjs/client.js

@@ -771,14 +771,31 @@ class TurbineClient {
      */
     async transaction(fn) {
         const client = await this.pool.connect();
+        /**
+         * Only true once BEGIN has actually succeeded. If BEGIN itself throws
+         * (e.g. a single-writer engine's transaction gate times out or rejects a
+         * re-entrant begin), issuing a "best-effort" ROLLBACK would be a stray
+         * statement from a context that never opened a transaction — on a driver
+         * with one shared engine handle (PowDB embedded) it would roll back a
+         * DIFFERENT caller's open transaction.
+         */
+        let began = false;
         try {
             await client.query(this.dialect.beginStatement());
+            began = true;
             const result = await fn(client);
             await client.query(this.dialect.commitStatement());
             return result;
         }
         catch (err) {
-            await client.query(this.dialect.rollbackStatement());
+            if (began) {
+                try {
+                    await client.query(this.dialect.rollbackStatement());
+                }
+                catch {
+                    // Best-effort rollback — the connection may have died mid-query.
+                }
+            }
             throw err;
         }
         finally {
@@ -812,11 +829,21 @@ class TurbineClient {
             }
         };
         let timedOut = false;
+        /**
+         * Only true once BEGIN has actually succeeded. If BEGIN itself throws —
+         * e.g. a single-writer engine's transaction gate times out in its FIFO
+         * queue or rejects a re-entrant begin (PowDB, E002/E017) — this context
+         * never opened a transaction, so the catch below must NOT issue its
+         * best-effort ROLLBACK: on a driver with one shared engine handle that
+         * stray ROLLBACK would tear down a DIFFERENT caller's open transaction.
+         */
+        let began = false;
         try {
             // BEGIN with optional isolation level — the dialect owns the keyword and
             // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`).
             const isolationSql = options?.isolationLevel ? ISOLATION_LEVELS[options.isolationLevel] : undefined;
             await client.query(this.dialect.beginStatement(isolationSql));
+            began = true;
             // Apply transaction-local session context (RLS / multi-tenant GUCs).
             // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
             // user fn. Any error here propagates to the catch below and rolls back
@@ -889,8 +916,11 @@ class TurbineClient {
             // If the timeout fired we already destroyed the connection — issuing a
             // ROLLBACK on a released client would throw "Client has already been
             // released". Skip the rollback in that case (the backend rolled back
-            // when its socket was closed).
-            if (!timedOut && !released) {
+            // when its socket was closed). Likewise skip it when BEGIN never
+            // succeeded (`began` false) — there is no transaction to roll back and
+            // the stray statement could hit another caller's transaction on a
+            // shared-handle engine.
+            if (began && !timedOut && !released) {
                 try {
                     await client.query(this.dialect.rollbackStatement());
                 }

package/dist/cjs/generate.js

@@ -57,21 +57,22 @@ function generate(options) {
     }
     (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
     const files = [];
+    const fileOptions = { noTimestamp: options.noTimestamp };
     // Generate types.ts
-    const typesContent = generateTypes(options.schema);
+    const typesContent = generateTypes(options.schema, fileOptions);
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'types.ts'), typesContent, 'utf-8');
     files.push('types.ts');
     // Generate metadata.ts
-    const metadataContent = generateMetadata(options.schema);
+    const metadataContent = generateMetadata(options.schema, fileOptions);
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'metadata.ts'), metadataContent, 'utf-8');
     files.push('metadata.ts');
     // Generate index.ts (configured client)
-    const indexContent = generateIndex(options.schema);
+    const indexContent = generateIndex(options.schema, fileOptions);
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'index.ts'), indexContent, 'utf-8');
     files.push('index.ts');
     // Generate zod.ts (optional — --zod flag)
     if (options.zod) {
-        const zodContent = generateZod(options.schema);
+        const zodContent = generateZod(options.schema, fileOptions);
         (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'zod.ts'), zodContent, 'utf-8');
         files.push('zod.ts');
     }
@@ -80,24 +81,51 @@ function generate(options) {
 // ---------------------------------------------------------------------------
 // types.ts generator
 // ---------------------------------------------------------------------------
-function generatedFileHeader() {
+function generatedFileHeader(options) {
+    // `noTimestamp` omits the volatile line entirely (T-8b) so regenerating an
+    // unchanged schema produces byte-identical files.
     return [
         '/**',
         ' * Auto-generated by turbine-orm — DO NOT EDIT',
         ' *',
-        ` * Generated at: ${new Date().toISOString()}`,
+        ...(options?.noTimestamp ? [] : [` * Generated at: ${new Date().toISOString()}`]),
         ' * @see https://turbineorm.dev',
         ' */',
         '',
     ];
 }
+/**
+ * The relations of a table that are safe to surface in the generated TYPE
+ * layer. A relation whose name equals a scalar column field would shadow the
+ * column: `interface XWithY extends X` becomes TS2430, the `XCreate & { y?: … }`
+ * intersection collapses (TS2322), and neither the column nor the relation is
+ * targetable. Introspection no longer produces such names (they are
+ * disambiguated at the source), but hand-written or legacy metadata may —
+ * skip those relations here with a warning instead of emitting broken types.
+ * The runtime metadata (metadata.ts) still carries every relation.
+ */
+function typeSafeRelations(table, warn = true) {
+    const columnFields = new Set(table.columns.map((c) => c.field));
+    const usable = [];
+    for (const [relName, rel] of Object.entries(table.relations)) {
+        if (columnFields.has(relName)) {
+            if (warn) {
+                console.warn(`[turbine] Relation "${relName}" on table "${table.name}" shadows a column field of the same name — ` +
+                    `omitting it from the generated types. Rename the relation (or the column) to expose it.`);
+            }
+            continue;
+        }
+        usable.push([relName, rel]);
+    }
+    return usable;
+}
 /**
  * Generate the contents of `types.ts` (entity interfaces, *Create / *Update,
  * and *Relations brand-field interfaces). Exported so tests can pin the
  * generator output without writing files to disk.
  */
-function generateTypes(schema) {
-    const lines = [...generatedFileHeader()];
+function generateTypes(schema, options) {
+    const lines = [...generatedFileHeader(options)];
     // We import UpdateOperatorInput so generated *Update types can express
     // atomic increment / decrement / multiply / divide / set operators on
     // numeric columns (TASK-3.4).
@@ -113,9 +141,15 @@ function generateTypes(schema) {
     // `${TargetType}Relations` (for deep inference) or `{}` (the no-relations
     // default) into each `RelationDescriptor`. Built once up-front because
     // relations can point at tables we haven't iterated to yet.
+    // Relations that can be surfaced in the type layer, computed once per table
+    // (relations that would shadow a scalar column field are excluded + warned).
+    const safeRelationsByTable = new Map();
+    for (const t of Object.values(schema.tables)) {
+        safeRelationsByTable.set(t.name, typeSafeRelations(t));
+    }
     const tablesWithRelations = new Set();
     for (const t of Object.values(schema.tables)) {
-        if (Object.keys(t.relations).length > 0)
+        if ((safeRelationsByTable.get(t.name) ?? []).length > 0)
             tablesWithRelations.add(t.name);
     }
     // Generate enum types
@@ -180,11 +214,12 @@ function generateTypes(schema) {
         // any depth — `RelationRelations<R[K]>` reads the third type parameter
         // and threads it into the next recursion step. If the target table has
         // no relations of its own, the descriptor uses `{}` (the default).
-        const hasRelations = Object.keys(table.relations).length > 0;
+        const safeRelations = safeRelationsByTable.get(table.name) ?? [];
+        const hasRelations = safeRelations.length > 0;
         if (hasRelations) {
             lines.push(`/** Available relations for the \`${table.name}\` table */`);
             lines.push(`export interface ${typeName}Relations {`);
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 // manyToMany is a collection too → 'many' cardinality (same as hasMany).
                 const cardinality = rel.type === 'hasMany' || rel.type === 'manyToMany' ? "'many'" : "'one'";
@@ -194,7 +229,7 @@ function generateTypes(schema) {
             lines.push('}');
             lines.push('');
             // --- Legacy per-relation interfaces (kept for backward compatibility) ---
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 if (rel.type === 'hasMany' || rel.type === 'manyToMany') {
                     lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
@@ -218,7 +253,8 @@ function generateTypes(schema) {
     // ---------------------------------------------------------------------------
     for (const table of Object.values(schema.tables)) {
         const typeName = entityName(table.name);
-        const hasRels = Object.keys(table.relations).length > 0;
+        const safeRelations = safeRelationsByTable.get(table.name) ?? [];
+        const hasRels = safeRelations.length > 0;
         // WhereUnique — union of unique constraint shapes, deduplicating PK
         const seen = new Set();
         const uniqueSets = [];
@@ -250,14 +286,14 @@ function generateTypes(schema) {
         // CreateInput / UpdateInput — extends base type with optional relation fields
         if (hasRels) {
             lines.push(`export type ${typeName}CreateInput = ${typeName}Create & {`);
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 lines.push(`  ${relName}?: ${targetType}NestedCreateInput;`);
             }
             lines.push('};');
             lines.push('');
             lines.push(`export type ${typeName}UpdateInput = ${typeName}Update & {`);
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 if (rel.type === 'hasMany') {
                     lines.push(`  ${relName}?: ${targetType}NestedUpdateInput;`);
@@ -273,7 +309,7 @@ function generateTypes(schema) {
     // Emit NestedCreateInput, NestedUpdateInput, ConnectOrCreate for every table
     for (const table of Object.values(schema.tables)) {
         const typeName = entityName(table.name);
-        const hasRels = Object.keys(table.relations).length > 0;
+        const hasRels = (safeRelationsByTable.get(table.name) ?? []).length > 0;
         // NestedCreateInput uses *CreateInput (which includes relation fields) when
         // the table has relations, otherwise falls back to the plain *Create type.
         const createRefType = hasRels ? `${typeName}CreateInput` : `${typeName}Create`;
@@ -358,8 +394,8 @@ function zodBaseType(col, enums) {
  * columns omitted, every remaining column optional). Exported so tests can pin
  * the output without writing files.
  */
-function generateZod(schema) {
-    const lines = [...generatedFileHeader()];
+function generateZod(schema, options) {
+    const lines = [...generatedFileHeader(options)];
     // `zod` is a USER dependency — this generated file imports it, but the Turbine
     // library runtime never does, so Zod stays out of the package's dep graph.
     lines.push("import { z } from 'zod';");
@@ -416,9 +452,9 @@ function generateZod(schema) {
 // ---------------------------------------------------------------------------
 // metadata.ts generator
 // ---------------------------------------------------------------------------
-function generateMetadata(schema) {
+function generateMetadata(schema, options) {
     const lines = [
-        ...generatedFileHeader(),
+        ...generatedFileHeader(options),
         "import type { SchemaMetadata } from 'turbine-orm';",
         '',
         'export const SCHEMA: SchemaMetadata = {',
@@ -518,10 +554,15 @@ function generateMetadata(schema) {
 // ---------------------------------------------------------------------------
 // index.ts generator (configured client with typed table accessors)
 // ---------------------------------------------------------------------------
-function generateIndex(schema) {
+function generateIndex(schema, options) {
     const tableEntries = Object.values(schema.tables);
+    // Must mirror generateTypes: `XRelations` only exists in types.ts when the
+    // table has at least one type-safe (non-column-shadowing) relation.
+    const hasSafeRelations = new Map();
+    for (const t of tableEntries)
+        hasSafeRelations.set(t.name, typeSafeRelations(t, false).length > 0);
     const lines = [
-        ...generatedFileHeader(),
+        ...generatedFileHeader(options),
         "import { TurbineClient as BaseTurbineClient, TransactionClient as BaseTransactionClient, QueryInterface } from 'turbine-orm';",
         "import type { TurbineConfig, TransactionOptions, DeferredQuery, PipelineResults } from 'turbine-orm';",
         "import { SCHEMA } from './metadata.js';",
@@ -530,7 +571,7 @@ function generateIndex(schema) {
     const typeImports = [];
     for (const t of tableEntries) {
         typeImports.push(entityName(t.name));
-        if (Object.keys(t.relations).length > 0) {
+        if (hasSafeRelations.get(t.name)) {
             typeImports.push(`${entityName(t.name)}Relations`);
         }
     }
@@ -552,7 +593,7 @@ function generateIndex(schema) {
     for (const table of tableEntries) {
         const typeName = entityName(table.name);
         const accessor = snakeToCamelStr(table.name);
-        const hasRelations = Object.keys(table.relations).length > 0;
+        const hasRelations = hasSafeRelations.get(table.name) === true;
         const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
         lines.push(`  /** Query interface for the \`${table.name}\` table (transaction-scoped) */`);
         lines.push(`  declare readonly ${accessor}: ${accessorType(table, genericArgs)};`);
@@ -594,7 +635,7 @@ function generateIndex(schema) {
     for (const table of tableEntries) {
         const typeName = entityName(table.name);
         const accessor = snakeToCamelStr(table.name);
-        const hasRelations = Object.keys(table.relations).length > 0;
+        const hasRelations = hasSafeRelations.get(table.name) === true;
         const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
         lines.push(`  /** Query interface for the \`${table.name}\` table */`);
         lines.push(`  declare readonly ${accessor}: ${accessorType(table, genericArgs)};`);
@@ -677,6 +718,11 @@ function serializeColumn(col) {
         `arrayType: '${escSQ(col.arrayType ?? col.pgArrayType)}'`,
         `pgArrayType: '${escSQ(col.pgArrayType)}'`,
     ];
+    // Cross-schema type marker — introspection records it only for types living
+    // outside the introspected schema; it must survive codegen or the runtime
+    // enum-cast guard in query/builder.ts loses the signal (N-5).
+    if (col.pgTypeSchema !== undefined)
+        parts.push(`pgTypeSchema: '${escSQ(col.pgTypeSchema)}'`);
     // Emit isGenerated only when set (server-generated serial/identity), so the
     // output stays byte-identical for the common client-default columns.
     if (col.isGenerated)

package/dist/cjs/index.js

@@ -35,7 +35,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ColumnBuilder = exports.applyManyToManyRelations = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
-exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.table = exports.defineSchema = exports.column = void 0;
+exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.schemaDefToMetadata = exports.table = exports.defineSchema = exports.column = void 0;
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "alloydb", { enumerable: true, get: function () { return index_js_1.alloydb; } });
 Object.defineProperty(exports, "cockroachdb", { enumerable: true, get: function () { return index_js_1.cockroachdb; } });
@@ -112,6 +112,9 @@ Object.defineProperty(exports, "column", { enumerable: true, get: function () {
 Object.defineProperty(exports, "defineSchema", { enumerable: true, get: function () { return schema_builder_js_1.defineSchema; } });
 // Legacy compat (deprecated — use object format with defineSchema)
 Object.defineProperty(exports, "table", { enumerable: true, get: function () { return schema_builder_js_1.table; } });
+// Schema metadata bridge — defineSchema() → SchemaMetadata without a live DB
+var schema_metadata_js_1 = require("./schema-metadata.js");
+Object.defineProperty(exports, "schemaDefToMetadata", { enumerable: true, get: function () { return schema_metadata_js_1.schemaDefToMetadata; } });
 // Schema SQL — generate DDL, diff, and push
 var schema_sql_js_1 = require("./schema-sql.js");
 Object.defineProperty(exports, "schemaDiff", { enumerable: true, get: function () { return schema_sql_js_1.schemaDiff; } });