turbine-orm 0.9.2 → 0.10.0

package/dist/cjs/cli/studio.js

@@ -74,7 +74,8 @@ async function startStudio(options) {
     });
     const authToken = (0, node_crypto_1.randomBytes)(24).toString('hex');
     const stateDir = (0, node_path_1.resolve)(options.stateDir ?? '.turbine');
-    const ctx = { pool, metadata, options, authToken, stateDir };
+    const statementTimeoutSQL = options.adapter?.statementTimeout?.(30) ?? `SET LOCAL statement_timeout = '30s'`;
+    const ctx = { pool, metadata, options, authToken, stateDir, statementTimeoutSQL };
     const server = (0, node_http_1.createServer)((req, res) => {
         handleRequest(req, res, ctx).catch((err) => {
             sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
@@ -293,7 +294,7 @@ async function apiTableRows(res, ctx, rawTableName, params) {
     const client = await ctx.pool.connect();
     try {
         await client.query('BEGIN READ ONLY');
-        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        await client.query(ctx.statementTimeoutSQL);
         const result = await client.query(sql, mainValues);
         const countResult = await client.query(countSql, countValues);
         await client.query('COMMIT');
@@ -359,7 +360,7 @@ async function apiQuery(req, res, ctx) {
     const client = await ctx.pool.connect();
     try {
         await client.query('BEGIN READ ONLY');
-        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        await client.query(ctx.statementTimeoutSQL);
         const started = Date.now();
         const result = await client.query(rawSql);
         const elapsedMs = Date.now() - started;
@@ -411,7 +412,7 @@ async function apiBuilder(req, res, ctx) {
     const client = await ctx.pool.connect();
     try {
         await client.query('BEGIN READ ONLY');
-        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        await client.query(ctx.statementTimeoutSQL);
         const started = Date.now();
         const result = await client.query(deferred.sql, deferred.params);
         const elapsedMs = Date.now() - started;

package/dist/cjs/generate.js

@@ -233,7 +233,14 @@ function generateMetadata(schema) {
         // relations
         lines.push('      relations: {');
         for (const [relName, rel] of Object.entries(table.relations)) {
-            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: '${escSQ(rel.foreignKey)}', referenceKey: '${escSQ(rel.referenceKey)}' },`);
+            // Emit foreignKey/referenceKey as string for single-column, array for composite
+            const fkLiteral = Array.isArray(rel.foreignKey)
+                ? `[${rel.foreignKey.map((c) => `'${escSQ(c)}'`).join(', ')}]`
+                : `'${escSQ(rel.foreignKey)}'`;
+            const refLiteral = Array.isArray(rel.referenceKey)
+                ? `[${rel.referenceKey.map((c) => `'${escSQ(c)}'`).join(', ')}]`
+                : `'${escSQ(rel.referenceKey)}'`;
+            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral} },`);
         }
         lines.push('      },');
         // indexes

package/dist/cjs/index.js

@@ -34,7 +34,13 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.turbineHttp = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.table = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.isDateType = exports.camelToSnake = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.PipelineError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.TurbineClient = exports.TransactionClient = void 0;
+exports.turbineHttp = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.table = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.PipelineError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = 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; } });
+Object.defineProperty(exports, "postgresql", { enumerable: true, get: function () { return index_js_1.postgresql; } });
+Object.defineProperty(exports, "timescale", { enumerable: true, get: function () { return index_js_1.timescale; } });
+Object.defineProperty(exports, "yugabytedb", { enumerable: true, get: function () { return index_js_1.yugabytedb; } });
 // Client
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "TransactionClient", { enumerable: true, get: function () { return client_js_1.TransactionClient; } });
@@ -71,12 +77,13 @@ var pipeline_js_1 = require("./pipeline.js");
 Object.defineProperty(exports, "executePipeline", { enumerable: true, get: function () { return pipeline_js_1.executePipeline; } });
 Object.defineProperty(exports, "pipelineSupported", { enumerable: true, get: function () { return pipeline_js_1.pipelineSupported; } });
 // Query builder
-var index_js_1 = require("./query/index.js");
-Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return index_js_1.QueryInterface; } });
+var index_js_2 = require("./query/index.js");
+Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return index_js_2.QueryInterface; } });
 // Schema utilities
 var schema_js_1 = require("./schema.js");
 Object.defineProperty(exports, "camelToSnake", { enumerable: true, get: function () { return schema_js_1.camelToSnake; } });
 Object.defineProperty(exports, "isDateType", { enumerable: true, get: function () { return schema_js_1.isDateType; } });
+Object.defineProperty(exports, "normalizeKeyColumns", { enumerable: true, get: function () { return schema_js_1.normalizeKeyColumns; } });
 Object.defineProperty(exports, "pgArrayType", { enumerable: true, get: function () { return schema_js_1.pgArrayType; } });
 Object.defineProperty(exports, "pgTypeToTs", { enumerable: true, get: function () { return schema_js_1.pgTypeToTs; } });
 Object.defineProperty(exports, "singularize", { enumerable: true, get: function () { return schema_js_1.singularize; } });

package/dist/cjs/introspect.js

@@ -72,13 +72,16 @@ const SQL_FOREIGN_KEYS = `
 const SQL_UNIQUE_CONSTRAINTS = `
   SELECT
     tc.table_name,
-    kcu.column_name
+    tc.constraint_name,
+    kcu.column_name,
+    kcu.ordinal_position
   FROM information_schema.table_constraints tc
   JOIN information_schema.key_column_usage kcu
     ON tc.constraint_name = kcu.constraint_name
     AND tc.table_schema = kcu.table_schema
   WHERE tc.constraint_type = 'UNIQUE'
     AND tc.table_schema = $1
+  ORDER BY tc.table_name, tc.constraint_name, kcu.ordinal_position
 `;
 const SQL_INDEXES = `
   SELECT tablename, indexname, indexdef
@@ -159,14 +162,22 @@ async function introspect(options) {
             pkByTable.get(row.table_name).push(row.column_name);
         }
         // ----- Group unique constraints by table -----
+        // Group rows by (table_name, constraint_name) to correctly handle multi-column unique constraints
         const uniqueByTable = new Map();
+        const uniqueConstraintGroups = new Map();
         for (const row of uniqueResult.rows) {
             if (!tableSet.has(row.table_name))
                 continue;
-            if (!uniqueByTable.has(row.table_name))
-                uniqueByTable.set(row.table_name, []);
-            // Each unique constraint may be multi-column; for simplicity, treat as single-col here
-            uniqueByTable.get(row.table_name).push([row.column_name]);
+            const key = `${row.table_name}::${row.constraint_name}`;
+            if (!uniqueConstraintGroups.has(key)) {
+                uniqueConstraintGroups.set(key, { table: row.table_name, columns: [] });
+            }
+            uniqueConstraintGroups.get(key).columns.push(row.column_name);
+        }
+        for (const { table, columns } of uniqueConstraintGroups.values()) {
+            if (!uniqueByTable.has(table))
+                uniqueByTable.set(table, []);
+            uniqueByTable.get(table).push(columns);
         }
         // ----- Group indexes by table -----
         const indexesByTable = new Map();
@@ -193,17 +204,25 @@ async function introspect(options) {
                 enums[row.typname] = [];
             enums[row.typname].push(row.enumlabel);
         }
-        const foreignKeys = [];
+        const fkGroups = new Map();
         for (const row of fkResult.rows) {
             if (!tableSet.has(row.source_table) || !tableSet.has(row.target_table))
                 continue;
-            foreignKeys.push({
-                sourceTable: row.source_table,
-                sourceColumn: row.source_column,
-                targetTable: row.target_table,
-                targetColumn: row.target_column,
-            });
+            const key = row.constraint_name;
+            if (!fkGroups.has(key)) {
+                fkGroups.set(key, {
+                    sourceTable: row.source_table,
+                    sourceColumns: [],
+                    targetTable: row.target_table,
+                    targetColumns: [],
+                    constraintName: key,
+                });
+            }
+            const entry = fkGroups.get(key);
+            entry.sourceColumns.push(row.source_column);
+            entry.targetColumns.push(row.target_column);
         }
+        const foreignKeys = Array.from(fkGroups.values());
         // ----- Build relations from foreign keys -----
         // Count FKs per (source, target) pair for disambiguation
         const fkCounts = new Map();
@@ -215,10 +234,17 @@ async function introspect(options) {
         for (const fk of foreignKeys) {
             const pairKey = `${fk.sourceTable}→${fk.targetTable}`;
             const needsDisambiguation = (fkCounts.get(pairKey) ?? 0) > 1;
+            // For single-column FKs, keep string form for backwards compatibility.
+            // For multi-column (composite) FKs, use array form.
+            const foreignKey = fk.sourceColumns.length === 1 ? fk.sourceColumns[0] : fk.sourceColumns;
+            const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
             // --- belongsTo on the source (child) table ---
             // e.g. posts.user_id → users.id creates posts.user (belongsTo)
+            // For composite FKs with disambiguation, use the constraint name
             const belongsToName = needsDisambiguation
-                ? (0, schema_js_1.snakeToCamel)(fk.sourceColumn.replace(/_id$/, ''))
+                ? 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));
             if (!relationsByTable.has(fk.sourceTable))
                 relationsByTable.set(fk.sourceTable, {});
@@ -227,13 +253,15 @@ async function introspect(options) {
                 name: belongsToName,
                 from: fk.sourceTable,
                 to: fk.targetTable,
-                foreignKey: fk.sourceColumn,
-                referenceKey: fk.targetColumn,
+                foreignKey,
+                referenceKey,
             };
             // --- hasMany on the target (parent) table ---
             // e.g. posts.user_id → users.id creates users.posts (hasMany)
             const hasManyName = needsDisambiguation
-                ? (0, schema_js_1.snakeToCamel)(`${fk.sourceTable}_by_${fk.sourceColumn.replace(/_id$/, '')}`)
+                ? 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);
             if (!relationsByTable.has(fk.targetTable))
                 relationsByTable.set(fk.targetTable, {});
@@ -242,8 +270,8 @@ async function introspect(options) {
                 name: hasManyName,
                 from: fk.targetTable,
                 to: fk.sourceTable,
-                foreignKey: fk.sourceColumn,
-                referenceKey: fk.targetColumn,
+                foreignKey,
+                referenceKey,
             };
         }
         // ----- Assemble TableMetadata for each table -----

package/dist/cjs/query/builder.js

@@ -99,6 +99,7 @@ function findArrayUniqueKey(value) {
     }
     return null;
 }
+// biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
 class QueryInterface {
     pool;
     table;
@@ -261,6 +262,7 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findUnique
     // -------------------------------------------------------------------------
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findUnique(args) {
         return this.executeWithMiddleware('findUnique', args, async () => {
             const deferred = this.buildFindUnique(args);
@@ -268,6 +270,7 @@ class QueryInterface {
             return deferred.transform(result);
         });
     }
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindUnique(args) {
         const columnsList = this.resolveColumns(args.select, args.omit);
         const whereObj = args.where;
@@ -363,6 +366,7 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findMany
     // -------------------------------------------------------------------------
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findMany(args) {
         this.maybeWarnUnlimited(args);
         // Dev-only: warn on deeply nested with clauses
@@ -420,6 +424,7 @@ class QueryInterface {
         }
         return maxDepth;
     }
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindMany(args) {
         const columnsList = this.resolveColumns(args?.select, args?.omit);
         const colKey = columnsList ? columnsList.join(',') : '*';
@@ -563,6 +568,7 @@ class QueryInterface {
      * }
      * ```
      */
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async *findManyStream(args) {
         const batchSize = Math.max(1, Math.floor(Number(args?.batchSize ?? 1000)));
         const hasRelations = !!args?.with;
@@ -619,6 +625,7 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findFirst — like findMany but returns a single row or null
     // -------------------------------------------------------------------------
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findFirst(args) {
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
             const deferred = this.buildFindFirst(args);
@@ -626,6 +633,7 @@ class QueryInterface {
             return deferred.transform(result);
         });
     }
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindFirst(args) {
         // Reuse findMany's SQL builder but force LIMIT 1
         const findManyArgs = { ...args, limit: 1 };
@@ -643,6 +651,7 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findFirstOrThrow — like findFirst but throws if no record found
     // -------------------------------------------------------------------------
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findFirstOrThrow(args) {
         return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
             const deferred = this.buildFindFirstOrThrow(args);
@@ -650,6 +659,7 @@ class QueryInterface {
             return deferred.transform(result);
         });
     }
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindFirstOrThrow(args) {
         const inner = this.buildFindFirst(args);
         return {
@@ -672,6 +682,7 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findUniqueOrThrow — like findUnique but throws if no record found
     // -------------------------------------------------------------------------
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findUniqueOrThrow(args) {
         return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
             const deferred = this.buildFindUniqueOrThrow(args);
@@ -679,6 +690,7 @@ class QueryInterface {
             return deferred.transform(result);
         });
     }
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindUniqueOrThrow(args) {
         const inner = this.buildFindUnique(args);
         return {
@@ -2016,15 +2028,15 @@ class QueryInterface {
         const qt = (0, utils_js_1.quoteIdent)(targetTable);
         const qSelf = (0, utils_js_1.quoteIdent)(this.table);
         const clauses = [];
-        // Correlation: link child table to parent table
+        // Correlation: link child table to parent table (supports composite FKs)
         let correlation;
         if (relDef.type === 'hasMany' || relDef.type === 'hasOne') {
             // parent.pk = child.fk
-            correlation = `${qt}.${(0, utils_js_1.quoteIdent)(relDef.foreignKey)} = ${qSelf}.${(0, utils_js_1.quoteIdent)(relDef.referenceKey)}`;
+            correlation = (0, utils_js_1.buildCorrelation)(qt, relDef.foreignKey, qSelf, relDef.referenceKey);
         }
         else {
             // belongsTo: parent.fk = child.pk
-            correlation = `${qt}.${(0, utils_js_1.quoteIdent)(relDef.referenceKey)} = ${qSelf}.${(0, utils_js_1.quoteIdent)(relDef.foreignKey)}`;
+            correlation = (0, utils_js_1.buildCorrelation)(qt, relDef.referenceKey, qSelf, relDef.foreignKey);
         }
         // "some": EXISTS (SELECT 1 FROM target WHERE correlation AND filter)
         if (filterObj.some !== undefined) {
@@ -2067,6 +2079,10 @@ class QueryInterface {
             if (value === undefined)
                 continue;
             const col = meta.columnMap[field] ?? (0, schema_js_1.camelToSnake)(field);
+            if (!meta.allColumns.includes(col)) {
+                throw new errors_js_1.ValidationError(`[turbine] Unknown field "${field}" in relation filter for table "${targetTable}". ` +
+                    `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
+            }
             const qCol = `${qt}.${(0, utils_js_1.quoteIdent)(col)}`;
             if (value === null) {
                 conditions.push(`${qCol} IS NULL`);
@@ -2474,12 +2490,13 @@ class QueryInterface {
         // Build WHERE — correlate to parent via parentRef (alias or table name).
         // For hasMany: target has FK, so alias.fk = parentRef.pk
         // For belongsTo: source has FK, so alias.pk = parentRef.fk (reversed)
+        // Supports composite foreign keys (string[]) via buildCorrelation.
         let whereClause;
         if (relDef.type === 'belongsTo' || relDef.type === 'hasOne') {
-            whereClause = `${alias}.${(0, utils_js_1.quoteIdent)(relDef.referenceKey)} = ${qParent}.${(0, utils_js_1.quoteIdent)(relDef.foreignKey)}`;
+            whereClause = (0, utils_js_1.buildCorrelation)(alias, relDef.referenceKey, qParent, relDef.foreignKey);
         }
         else {
-            whereClause = `${alias}.${(0, utils_js_1.quoteIdent)(relDef.foreignKey)} = ${qParent}.${(0, utils_js_1.quoteIdent)(relDef.referenceKey)}`;
+            whereClause = (0, utils_js_1.buildCorrelation)(alias, relDef.foreignKey, qParent, relDef.referenceKey);
         }
         // Additional filters — properly parameterized
         if (spec !== true && spec.where) {

package/dist/cjs/query/index.js

@@ -7,8 +7,9 @@
  * former monolithic `import { … } from './query.js'`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryInterface = exports.sqlToPreparedName = exports.quoteIdent = exports.OPERATOR_KEYS = exports.LRUCache = exports.fnv1a64Hex = exports.escSingleQuote = exports.escapeLike = void 0;
+exports.QueryInterface = exports.sqlToPreparedName = exports.quoteIdent = exports.OPERATOR_KEYS = exports.LRUCache = exports.fnv1a64Hex = exports.escSingleQuote = exports.escapeLike = exports.buildCorrelation = void 0;
 var utils_js_1 = require("./utils.js");
+Object.defineProperty(exports, "buildCorrelation", { enumerable: true, get: function () { return utils_js_1.buildCorrelation; } });
 Object.defineProperty(exports, "escapeLike", { enumerable: true, get: function () { return utils_js_1.escapeLike; } });
 Object.defineProperty(exports, "escSingleQuote", { enumerable: true, get: function () { return utils_js_1.escSingleQuote; } });
 Object.defineProperty(exports, "fnv1a64Hex", { enumerable: true, get: function () { return utils_js_1.fnv1a64Hex; } });

package/dist/cjs/query/utils.js

@@ -11,6 +11,7 @@ exports.escSingleQuote = escSingleQuote;
 exports.escapeLike = escapeLike;
 exports.fnv1a64Hex = fnv1a64Hex;
 exports.sqlToPreparedName = sqlToPreparedName;
+exports.buildCorrelation = buildCorrelation;
 // ---------------------------------------------------------------------------
 // Identifier quoting — prevents SQL injection via table/column names
 // ---------------------------------------------------------------------------
@@ -120,3 +121,20 @@ exports.OPERATOR_KEYS = new Set([
     'endsWith',
     'mode',
 ]);
+// ---------------------------------------------------------------------------
+// Composite key correlation helper
+// ---------------------------------------------------------------------------
+/**
+ * Build a correlation clause joining columns between two table references.
+ * Handles both single-column (string) and multi-column (string[]) foreign keys.
+ *
+ * For single-column: `"alias"."col" = "parent"."col"`
+ * For multi-column:  `"alias"."col_a" = "parent"."ref_a" AND "alias"."col_b" = "parent"."ref_b"`
+ */
+function buildCorrelation(leftRef, leftColumns, rightRef, rightColumns) {
+    const leftCols = Array.isArray(leftColumns) ? leftColumns : [leftColumns];
+    const rightCols = Array.isArray(rightColumns) ? rightColumns : [rightColumns];
+    return leftCols
+        .map((col, i) => `${leftRef}.${quoteIdent(col)} = ${rightRef}.${quoteIdent(rightCols[i])}`)
+        .join(' AND ');
+}

package/dist/cjs/schema.js

@@ -6,6 +6,7 @@
  * They're used by the query builder, code generator, and CLI.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeKeyColumns = normalizeKeyColumns;
 exports.pgTypeToTs = pgTypeToTs;
 exports.isDateType = isDateType;
 exports.pgArrayType = pgArrayType;
@@ -14,6 +15,13 @@ exports.camelToSnake = camelToSnake;
 exports.snakeToPascal = snakeToPascal;
 exports.singularize = singularize;
 // ---------------------------------------------------------------------------
+// Helpers for composite key handling
+// ---------------------------------------------------------------------------
+/** Normalize foreignKey/referenceKey to always be an array for uniform processing */
+function normalizeKeyColumns(key) {
+    return Array.isArray(key) ? key : [key];
+}
+// ---------------------------------------------------------------------------
 // Type mapping: Postgres → TypeScript
 // ---------------------------------------------------------------------------
 const PG_TO_TS = {

package/dist/cli/config.d.ts

@@ -21,6 +21,17 @@ export interface TurbineCliConfig {
     seedFile?: string;
     /** Schema builder file path (for push command) */
     schemaFile?: string;
+    /**
+     * Database adapter for PostgreSQL-compatible databases that need
+     * dialect-specific behavior (e.g. CockroachDB, YugabyteDB).
+     *
+     * @example
+     * ```ts
+     * import { cockroachdb } from 'turbine-orm/adapters';
+     * export default { url: process.env.DATABASE_URL, adapter: cockroachdb };
+     * ```
+     */
+    adapter?: import('../adapters/index.js').DatabaseAdapter;
 }
 /**
  * Attempt to load a turbine config file from the current directory.

package/dist/cli/index.js

@@ -888,7 +888,8 @@ async function cmdStatus(_args, config) {
                 const isLast = i === rels.length - 1;
                 const prefix = isLast ? symbols.teeEnd : symbols.tee;
                 const relColor = rel.type === 'hasMany' ? blue : yellow;
-                console.log(`    ${dim(prefix)} ${relColor(relName)} ${dim(symbols.arrow)} ${rel.to} ${dim(`(${rel.type}, FK: ${rel.foreignKey})`)}`);
+                const fkDisplay = Array.isArray(rel.foreignKey) ? rel.foreignKey.join(', ') : rel.foreignKey;
+                console.log(`    ${dim(prefix)} ${relColor(relName)} ${dim(symbols.arrow)} ${rel.to} ${dim(`(${rel.type}, FK: ${fkDisplay})`)}`);
             }
         }
         newline();

package/dist/cli/migrate.d.ts

@@ -11,6 +11,7 @@
  *   -- DOWN
  *   DROP TABLE users;
  */
+import type { DatabaseAdapter } from '../adapters/index.js';
 export interface MigrationFile {
     /** Full filename (e.g. "20260325120000_create_users.sql") */
     filename: string;
@@ -113,6 +114,7 @@ export declare function migrateUp(connectionString: string, migrationsDir: strin
     step?: number;
     allowDrift?: boolean /** @deprecated use allowDrift */;
     force?: boolean;
+    adapter?: DatabaseAdapter;
 }): Promise<{
     applied: MigrationFile[];
     errors: Array<{
@@ -130,6 +132,7 @@ export declare function migrateUp(connectionString: string, migrationsDir: strin
  */
 export declare function migrateDown(connectionString: string, migrationsDir: string, options?: {
     step?: number;
+    adapter?: DatabaseAdapter;
 }): Promise<{
     rolledBack: MigrationFile[];
     errors: Array<{

package/dist/cli/migrate.js

@@ -15,6 +15,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import pg from 'pg';
+import { postgresql } from '../adapters/index.js';
 import { MigrationError } from '../errors.js';
 import { quoteIdent } from '../query/index.js';
 // ---------------------------------------------------------------------------
@@ -234,12 +235,14 @@ async function getCurrentDatabaseName(client) {
     const result = await client.query(`SELECT current_database()`);
     return result.rows[0]?.current_database ?? '';
 }
-async function acquireLock(client, lockId) {
-    const result = await client.query(`SELECT pg_try_advisory_lock($1) AS locked`, [lockId]);
-    return result.rows[0]?.locked ?? false;
+async function acquireLock(client, lockId, adapter) {
+    const a = adapter ?? postgresql;
+    // pg.Client satisfies PgCompatPoolClient (query + release)
+    return a.acquireLock(client, lockId);
 }
-async function releaseLock(client, lockId) {
-    await client.query(`SELECT pg_advisory_unlock($1)`, [lockId]);
+async function releaseLock(client, lockId, adapter) {
+    const a = adapter ?? postgresql;
+    await a.releaseLock(client, lockId);
 }
 /**
  * Validate that applied migration files have not been modified or deleted since they were run.
@@ -306,8 +309,10 @@ export async function migrateUp(connectionString, migrationsDir, options) {
         // sibling databases on the same Postgres cluster do not contend.
         const dbName = await getCurrentDatabaseName(client);
         const lockId = deriveLockId(dbName);
-        // Acquire advisory lock to prevent concurrent migrations
-        const gotLock = await acquireLock(client, lockId);
+        // Acquire lock to prevent concurrent migrations.
+        // The adapter determines the strategy (advisory lock vs table lock).
+        const adapter = options?.adapter;
+        const gotLock = await acquireLock(client, lockId, adapter);
         if (!gotLock) {
             throw new MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
@@ -379,7 +384,7 @@ export async function migrateUp(connectionString, migrationsDir, options) {
             return { applied: results, errors };
         }
         finally {
-            await releaseLock(client, lockId);
+            await releaseLock(client, lockId, adapter);
         }
     }
     finally {
@@ -402,7 +407,8 @@ export async function migrateDown(connectionString, migrationsDir, options) {
         // sibling databases on the same cluster do not contend.
         const dbName = await getCurrentDatabaseName(client);
         const lockId = deriveLockId(dbName);
-        const gotLock = await acquireLock(client, lockId);
+        const adapter = options?.adapter;
+        const gotLock = await acquireLock(client, lockId, adapter);
         if (!gotLock) {
             throw new MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
@@ -449,7 +455,7 @@ export async function migrateDown(connectionString, migrationsDir, options) {
             return { rolledBack: results, errors };
         }
         finally {
-            await releaseLock(client, lockId);
+            await releaseLock(client, lockId, adapter);
         }
     }
     finally {

package/dist/cli/studio.d.ts

@@ -28,6 +28,8 @@ export interface StudioOptions {
     exclude?: string[];
     /** Directory where studio-queries.json is persisted. Defaults to `.turbine/` in cwd. */
     stateDir?: string;
+    /** Database adapter for dialect-specific behavior (e.g. statement timeout syntax). */
+    adapter?: import('../adapters/index.js').DatabaseAdapter;
 }
 export interface StudioHandle {
     /** Shut down the server + pool cleanly. */
@@ -43,6 +45,8 @@ export interface StudioContext {
     options: StudioOptions;
     authToken: string;
     stateDir: string;
+    /** Resolved statement timeout SQL string (adapter-aware). */
+    statementTimeoutSQL: string;
 }
 /**
  * Start the Studio server. Returns a handle with the session token, a pre-built

package/dist/cli/studio.js

@@ -59,7 +59,8 @@ export async function startStudio(options) {
     });
     const authToken = randomBytes(24).toString('hex');
     const stateDir = pathResolve(options.stateDir ?? '.turbine');
-    const ctx = { pool, metadata, options, authToken, stateDir };
+    const statementTimeoutSQL = options.adapter?.statementTimeout?.(30) ?? `SET LOCAL statement_timeout = '30s'`;
+    const ctx = { pool, metadata, options, authToken, stateDir, statementTimeoutSQL };
     const server = createServer((req, res) => {
         handleRequest(req, res, ctx).catch((err) => {
             sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
@@ -278,7 +279,7 @@ export async function apiTableRows(res, ctx, rawTableName, params) {
     const client = await ctx.pool.connect();
     try {
         await client.query('BEGIN READ ONLY');
-        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        await client.query(ctx.statementTimeoutSQL);
         const result = await client.query(sql, mainValues);
         const countResult = await client.query(countSql, countValues);
         await client.query('COMMIT');
@@ -344,7 +345,7 @@ async function apiQuery(req, res, ctx) {
     const client = await ctx.pool.connect();
     try {
         await client.query('BEGIN READ ONLY');
-        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        await client.query(ctx.statementTimeoutSQL);
         const started = Date.now();
         const result = await client.query(rawSql);
         const elapsedMs = Date.now() - started;
@@ -396,7 +397,7 @@ export async function apiBuilder(req, res, ctx) {
     const client = await ctx.pool.connect();
     try {
         await client.query('BEGIN READ ONLY');
-        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        await client.query(ctx.statementTimeoutSQL);
         const started = Date.now();
         const result = await client.query(deferred.sql, deferred.params);
         const elapsedMs = Date.now() - started;

package/dist/generate.js

@@ -229,7 +229,14 @@ function generateMetadata(schema) {
         // relations
         lines.push('      relations: {');
         for (const [relName, rel] of Object.entries(table.relations)) {
-            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: '${escSQ(rel.foreignKey)}', referenceKey: '${escSQ(rel.referenceKey)}' },`);
+            // Emit foreignKey/referenceKey as string for single-column, array for composite
+            const fkLiteral = Array.isArray(rel.foreignKey)
+                ? `[${rel.foreignKey.map((c) => `'${escSQ(c)}'`).join(', ')}]`
+                : `'${escSQ(rel.foreignKey)}'`;
+            const refLiteral = Array.isArray(rel.referenceKey)
+                ? `[${rel.referenceKey.map((c) => `'${escSQ(c)}'`).join(', ')}]`
+                : `'${escSQ(rel.referenceKey)}'`;
+            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral} },`);
         }
         lines.push('      },');
         // indexes

package/dist/index.d.ts

@@ -32,6 +32,8 @@
  * await db.disconnect();
  * ```
  */
+export type { DatabaseAdapter, IntrospectionOverrides } from './adapters/index.js';
+export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
 export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, } from './client.js';
 export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, PipelineError, type PipelineResultSlot, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
 export { type GenerateOptions, generate } from './generate.js';
@@ -39,7 +41,7 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
 export { type AggregateArgs, type AggregateResult, type ArrayFilter, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type JsonFilter, type OrderDirection, QueryInterface, type RelationDescriptor, type RelationFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export type { ColumnMetadata, IndexMetadata, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
-export { camelToSnake, isDateType, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
+export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 export { ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, defineSchema, type SchemaDef, type TableDef, table, } from './schema-builder.js';
 export { type AlterColumnDef, type AlterDef, type DiffResult, type PushResult, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 export { type TurbineHttpOptions, turbineHttp } from './serverless.js';