turbine-orm 0.9.1 → 0.10.0

package/dist/cjs/query/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * turbine-orm — Query builder barrel
+ *
+ * Re-exports every public symbol from the query submodules so that
+ * `import { … } from './query/index.js'` is a drop-in replacement for the
+ * 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 = 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; } });
+Object.defineProperty(exports, "LRUCache", { enumerable: true, get: function () { return utils_js_1.LRUCache; } });
+Object.defineProperty(exports, "OPERATOR_KEYS", { enumerable: true, get: function () { return utils_js_1.OPERATOR_KEYS; } });
+Object.defineProperty(exports, "quoteIdent", { enumerable: true, get: function () { return utils_js_1.quoteIdent; } });
+Object.defineProperty(exports, "sqlToPreparedName", { enumerable: true, get: function () { return utils_js_1.sqlToPreparedName; } });
+var builder_js_1 = require("./builder.js");
+Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return builder_js_1.QueryInterface; } });

package/dist/cjs/query/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * turbine-orm — Query builder types
+ *
+ * All exported type and interface definitions for the query builder module.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/query/utils.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * turbine-orm — Query builder utilities
+ *
+ * Standalone utility functions and classes used by the query builder.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPERATOR_KEYS = exports.LRUCache = void 0;
+exports.quoteIdent = quoteIdent;
+exports.escSingleQuote = escSingleQuote;
+exports.escapeLike = escapeLike;
+exports.fnv1a64Hex = fnv1a64Hex;
+exports.sqlToPreparedName = sqlToPreparedName;
+exports.buildCorrelation = buildCorrelation;
+// ---------------------------------------------------------------------------
+// Identifier quoting — prevents SQL injection via table/column names
+// ---------------------------------------------------------------------------
+/**
+ * Quote a SQL identifier (table name, column name) using Postgres double-quote
+ * rules: wrap in double quotes, escape internal double quotes by doubling them.
+ *
+ * @example
+ *   quoteIdent('users')       → '"users"'
+ *   quoteIdent('my"table')    → '"my""table"'
+ *   quoteIdent('user name')   → '"user name"'
+ */
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/**
+ * Escape single quotes for use as string keys in json_build_object().
+ * Doubles single quotes per SQL quoting rules.
+ */
+function escSingleQuote(s) {
+    return s.replace(/'/g, "''");
+}
+/**
+ * Escape LIKE pattern metacharacters: %, _, and \.
+ * Must be used with `ESCAPE '\'` in the LIKE clause.
+ */
+function escapeLike(value) {
+    return value.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
+}
+// ---------------------------------------------------------------------------
+// LRU cache — bounded SQL template cache to prevent memory leaks
+// ---------------------------------------------------------------------------
+/**
+ * Simple LRU (Least Recently Used) cache with a fixed maximum size.
+ * When the cache exceeds maxSize, the oldest (least recently used) entry is evicted.
+ * Uses Map insertion order for O(1) eviction.
+ */
+class LRUCache {
+    maxSize;
+    cache = new Map();
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const value = this.cache.get(key);
+        if (value !== undefined) {
+            // Move to end (most recently used)
+            this.cache.delete(key);
+            this.cache.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        else if (this.cache.size >= this.maxSize) {
+            // Delete oldest (first) entry
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined)
+                this.cache.delete(firstKey);
+        }
+        this.cache.set(key, value);
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+exports.LRUCache = LRUCache;
+/**
+ * FNV-1a 64-bit hash returning 16 lowercase hex chars.
+ * Single-loop string iteration. Uses BigInt for 64-bit math.
+ *
+ * @internal Exported for testing only.
+ */
+function fnv1a64Hex(s) {
+    // FNV-1a offset basis and prime for 64-bit
+    let hash = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    const mask = 0xffffffffffffffffn; // 64-bit mask
+    for (let i = 0; i < s.length; i++) {
+        hash ^= BigInt(s.charCodeAt(i));
+        hash = (hash * prime) & mask;
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+/**
+ * Derive a prepared-statement name from a SQL string.
+ * Format: `t_<16hex>` — always 18 chars, well under NAMEDATALEN (63).
+ *
+ * @internal Exported for testing only.
+ */
+function sqlToPreparedName(sql) {
+    return `t_${fnv1a64Hex(sql)}`;
+}
+/** Known operator keys — used to detect operator objects vs plain values */
+exports.OPERATOR_KEYS = new Set([
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'not',
+    'in',
+    'notIn',
+    'contains',
+    'startsWith',
+    '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-sql.js

@@ -14,7 +14,7 @@ exports.schemaDiff = schemaDiff;
 exports.schemaPush = schemaPush;
 exports.schemaToSQLString = schemaToSQLString;
 const pg_1 = __importDefault(require("pg"));
-const query_js_1 = require("./query.js");
+const index_js_1 = require("./query/index.js");
 const schema_js_1 = require("./schema.js");
 // ---------------------------------------------------------------------------
 // SQL Generation — SchemaDef → CREATE TABLE statements
@@ -143,18 +143,18 @@ function generateCreateTable(table, resolveRef) {
     }
     // Append a table-level PRIMARY KEY constraint when a composite PK is set.
     if (compositePk) {
-        const cols = compositePk.map((c) => (0, query_js_1.quoteIdent)((0, schema_js_1.camelToSnake)(c))).join(', ');
+        const cols = compositePk.map((c) => (0, index_js_1.quoteIdent)((0, schema_js_1.camelToSnake)(c))).join(', ');
         columnDefs.push(`PRIMARY KEY (${cols})`);
     }
     const body = columnDefs.map((d) => `    ${d}`).join(',\n');
-    return `CREATE TABLE ${(0, query_js_1.quoteIdent)(tableName)} (\n${body}\n);`;
+    return `CREATE TABLE ${(0, index_js_1.quoteIdent)(tableName)} (\n${body}\n);`;
 }
 /**
  * Generate a single column definition line (e.g. "id BIGSERIAL PRIMARY KEY").
  */
 function generateColumnDef(fieldName, config, resolveRef) {
     const snakeName = (0, schema_js_1.camelToSnake)(fieldName);
-    const parts = [(0, query_js_1.quoteIdent)(snakeName)];
+    const parts = [(0, index_js_1.quoteIdent)(snakeName)];
     // Type
     if (config.type === 'VARCHAR' && config.maxLength != null) {
         parts.push(`VARCHAR(${config.maxLength})`);
@@ -193,7 +193,7 @@ function generateColumnDef(fieldName, config, resolveRef) {
         if (refParts.length === 2) {
             const rawTable = refParts[0];
             const refTable = resolveRef ? resolveRef(rawTable) : rawTable;
-            parts.push(`REFERENCES ${(0, query_js_1.quoteIdent)(refTable)}(${(0, query_js_1.quoteIdent)(refParts[1])})`);
+            parts.push(`REFERENCES ${(0, index_js_1.quoteIdent)(refTable)}(${(0, index_js_1.quoteIdent)(refParts[1])})`);
         }
     }
     return parts.join(' ');
@@ -242,7 +242,7 @@ function generateForeignKeyIndexes(table) {
         if (config.referencesTarget) {
             const snakeName = (0, schema_js_1.camelToSnake)(fieldName);
             const indexName = `idx_${table.name}_${snakeName}`;
-            indexes.push(`CREATE INDEX ${(0, query_js_1.quoteIdent)(indexName)} ON ${(0, query_js_1.quoteIdent)(table.name)}(${(0, query_js_1.quoteIdent)(snakeName)});`);
+            indexes.push(`CREATE INDEX ${(0, index_js_1.quoteIdent)(indexName)} ON ${(0, index_js_1.quoteIdent)(table.name)}(${(0, index_js_1.quoteIdent)(snakeName)});`);
         }
     }
     return indexes;
@@ -317,7 +317,7 @@ async function schemaDiff(schema, connectionString) {
                 const fkIndexes = generateForeignKeyIndexes(tableDef);
                 result.statements.push(...fkIndexes);
                 // Reverse: DROP TABLE (with indexes — they drop automatically)
-                result.reverseStatements.unshift(`DROP TABLE IF EXISTS ${(0, query_js_1.quoteIdent)(ddlName)} CASCADE;`);
+                result.reverseStatements.unshift(`DROP TABLE IF EXISTS ${(0, index_js_1.quoteIdent)(ddlName)} CASCADE;`);
             }
         }
         // Tables to drop (in DB but not in schema)
@@ -342,8 +342,8 @@ async function schemaDiff(schema, connectionString) {
                 if (!dbCol) {
                     // Column exists in schema but not in DB — ADD COLUMN
                     const colDef = generateColumnDef(fieldName, config, resolveRef);
-                    const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ADD COLUMN ${colDef};`;
-                    const reverseSql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} DROP COLUMN ${(0, query_js_1.quoteIdent)(snakeName)};`;
+                    const sql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ADD COLUMN ${colDef};`;
+                    const reverseSql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} DROP COLUMN ${(0, index_js_1.quoteIdent)(snakeName)};`;
                     alterDef.columns.push({ column: snakeName, action: 'add', sql, reverseSql });
                     result.statements.push(sql);
                     result.reverseStatements.unshift(reverseSql);
@@ -354,8 +354,8 @@ async function schemaDiff(schema, connectionString) {
                 if (expectedUdt && dbCol.udtName !== expectedUdt) {
                     const sqlType = config.type === 'VARCHAR' && config.maxLength ? `VARCHAR(${config.maxLength})` : config.type;
                     const oldSqlType = udtToSqlType(dbCol.udtName, dbCol.maxLength);
-                    const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} TYPE ${sqlType} USING ${(0, query_js_1.quoteIdent)(snakeName)}::${sqlType};`;
-                    const reverseSql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} TYPE ${oldSqlType} USING ${(0, query_js_1.quoteIdent)(snakeName)}::${oldSqlType};`;
+                    const sql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} TYPE ${sqlType} USING ${(0, index_js_1.quoteIdent)(snakeName)}::${sqlType};`;
+                    const reverseSql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} TYPE ${oldSqlType} USING ${(0, index_js_1.quoteIdent)(snakeName)}::${oldSqlType};`;
                     alterDef.columns.push({ column: snakeName, action: 'alter_type', sql, reverseSql });
                     result.statements.push(sql);
                     result.reverseStatements.unshift(reverseSql);
@@ -364,15 +364,15 @@ async function schemaDiff(schema, connectionString) {
                 const shouldBeNotNull = config.isNotNull || config.isPrimaryKey || config.type === 'BIGSERIAL';
                 const isCurrentlyNullable = dbCol.isNullable;
                 if (shouldBeNotNull && isCurrentlyNullable && !config.isNullable) {
-                    const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} SET NOT NULL;`;
-                    const reverseSql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} DROP NOT NULL;`;
+                    const sql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} SET NOT NULL;`;
+                    const reverseSql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} DROP NOT NULL;`;
                     alterDef.columns.push({ column: snakeName, action: 'set_not_null', sql, reverseSql });
                     result.statements.push(sql);
                     result.reverseStatements.unshift(reverseSql);
                 }
                 else if (!shouldBeNotNull && !isCurrentlyNullable && config.isNullable) {
-                    const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} DROP NOT NULL;`;
-                    const reverseSql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} SET NOT NULL;`;
+                    const sql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} DROP NOT NULL;`;
+                    const reverseSql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} SET NOT NULL;`;
                     alterDef.columns.push({ column: snakeName, action: 'drop_not_null', sql, reverseSql });
                     result.statements.push(sql);
                     result.reverseStatements.unshift(reverseSql);
@@ -384,16 +384,16 @@ async function schemaDiff(schema, connectionString) {
                     const dbDefault = dbCol.columnDefault;
                     if (schemaDefault && !dbDefault) {
                         // Schema has default, DB doesn't
-                        const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} SET DEFAULT ${schemaDefault};`;
-                        const reverseSql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} DROP DEFAULT;`;
+                        const sql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} SET DEFAULT ${schemaDefault};`;
+                        const reverseSql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} DROP DEFAULT;`;
                         alterDef.columns.push({ column: snakeName, action: 'set_default', sql, reverseSql });
                         result.statements.push(sql);
                         result.reverseStatements.unshift(reverseSql);
                     }
                     else if (!schemaDefault && dbDefault && !isSequenceDefault(dbDefault)) {
                         // DB has a non-sequence default, schema doesn't
-                        const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} DROP DEFAULT;`;
-                        const reverseSql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} SET DEFAULT ${dbDefault};`;
+                        const sql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} DROP DEFAULT;`;
+                        const reverseSql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} SET DEFAULT ${dbDefault};`;
                         alterDef.columns.push({ column: snakeName, action: 'drop_default', sql, reverseSql });
                         result.statements.push(sql);
                         result.reverseStatements.unshift(reverseSql);
@@ -403,8 +403,8 @@ async function schemaDiff(schema, connectionString) {
                         !isSequenceDefault(dbDefault) &&
                         !defaultsMatch(schemaDefault, dbDefault)) {
                         // Both have defaults but they differ
-                        const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} SET DEFAULT ${schemaDefault};`;
-                        const reverseSql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} SET DEFAULT ${dbDefault};`;
+                        const sql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} SET DEFAULT ${schemaDefault};`;
+                        const reverseSql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, index_js_1.quoteIdent)(snakeName)} SET DEFAULT ${dbDefault};`;
                         alterDef.columns.push({ column: snakeName, action: 'set_default', sql, reverseSql });
                         result.statements.push(sql);
                         result.reverseStatements.unshift(reverseSql);
@@ -416,16 +416,16 @@ async function schemaDiff(schema, connectionString) {
                     const wantsUnique = config.isUnique === true;
                     if (wantsUnique && !hasDbUnique) {
                         const constraintName = `${tableName}_${snakeName}_key`;
-                        const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ADD CONSTRAINT ${(0, query_js_1.quoteIdent)(constraintName)} UNIQUE (${(0, query_js_1.quoteIdent)(snakeName)});`;
-                        const reverseSql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} DROP CONSTRAINT ${(0, query_js_1.quoteIdent)(constraintName)};`;
+                        const sql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ADD CONSTRAINT ${(0, index_js_1.quoteIdent)(constraintName)} UNIQUE (${(0, index_js_1.quoteIdent)(snakeName)});`;
+                        const reverseSql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} DROP CONSTRAINT ${(0, index_js_1.quoteIdent)(constraintName)};`;
                         alterDef.columns.push({ column: snakeName, action: 'add_unique', sql, reverseSql });
                         result.statements.push(sql);
                         result.reverseStatements.unshift(reverseSql);
                     }
                     else if (!wantsUnique && hasDbUnique) {
                         const constraintName = tableUniques[snakeName];
-                        const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} DROP CONSTRAINT ${(0, query_js_1.quoteIdent)(constraintName)};`;
-                        const reverseSql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ADD CONSTRAINT ${(0, query_js_1.quoteIdent)(constraintName)} UNIQUE (${(0, query_js_1.quoteIdent)(snakeName)});`;
+                        const sql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} DROP CONSTRAINT ${(0, index_js_1.quoteIdent)(constraintName)};`;
+                        const reverseSql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} ADD CONSTRAINT ${(0, index_js_1.quoteIdent)(constraintName)} UNIQUE (${(0, index_js_1.quoteIdent)(snakeName)});`;
                         alterDef.columns.push({ column: snakeName, action: 'drop_unique', sql, reverseSql });
                         result.statements.push(sql);
                         result.reverseStatements.unshift(reverseSql);
@@ -436,7 +436,7 @@ async function schemaDiff(schema, connectionString) {
             for (const dbColName of Object.keys(dbCols)) {
                 const hasField = Object.entries(tableDef.columns).some(([fieldName]) => (0, schema_js_1.camelToSnake)(fieldName) === dbColName);
                 if (!hasField) {
-                    const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} DROP COLUMN ${(0, query_js_1.quoteIdent)(dbColName)};`;
+                    const sql = `ALTER TABLE ${(0, index_js_1.quoteIdent)(tableName)} DROP COLUMN ${(0, index_js_1.quoteIdent)(dbColName)};`;
                     const reverseSql = `-- Cannot auto-reverse DROP COLUMN for "${dbColName}" — add it back manually`;
                     alterDef.columns.push({ column: dbColName, action: 'drop', sql, reverseSql });
                     // Don't auto-add drops to statements for safety — user must opt in

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,8 +15,9 @@ 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.js';
+import { quoteIdent } from '../query/index.js';
 // ---------------------------------------------------------------------------
 // Tracking table management
 // ---------------------------------------------------------------------------
@@ -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

@@ -23,7 +23,7 @@ import { platform } from 'node:os';
 import { dirname, resolve as pathResolve } from 'node:path';
 import pg from 'pg';
 import { introspect } from '../introspect.js';
-import { QueryInterface, quoteIdent } from '../query.js';
+import { QueryInterface, quoteIdent } from '../query/index.js';
 import { STUDIO_HTML } from './studio-ui.generated.js';
 // ---------------------------------------------------------------------------
 // Main entry point
@@ -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/client.d.ts

@@ -24,7 +24,7 @@
 import pg from 'pg';
 import { type ErrorMessageMode } from './errors.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
-import { type DeferredQuery, QueryInterface, type QueryInterfaceOptions } from './query.js';
+import { type DeferredQuery, QueryInterface, type QueryInterfaceOptions } from './query/index.js';
 import type { SchemaMetadata } from './schema.js';
 /**
  * Minimal pg-compatible query result.

package/dist/client.js

@@ -24,7 +24,7 @@
 import pg from 'pg';
 import { setErrorMessageMode, TimeoutError, wrapPgError } from './errors.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
-import { QueryInterface } from './query.js';
+import { QueryInterface } from './query/index.js';
 /** Maps isolation level names to SQL */
 const ISOLATION_LEVELS = {
     ReadUncommitted: 'READ UNCOMMITTED',

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,14 +32,16 @@
  * 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';
 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.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';

package/dist/index.js

@@ -32,6 +32,7 @@
  * await db.disconnect();
  * ```
  */
+export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
 // Client
 export { TransactionClient, TurbineClient, } from './client.js';
 // Error types
@@ -43,9 +44,9 @@ export { introspect } from './introspect.js';
 // Pipeline
 export { executePipeline, pipelineSupported } from './pipeline.js';
 // Query builder
-export { QueryInterface, } from './query.js';
+export { QueryInterface, } from './query/index.js';
 // Schema utilities
-export { camelToSnake, isDateType, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
+export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 // Schema builder — define schemas in TypeScript
 export { ColumnBuilder, column, defineSchema, 
 // Legacy compat (deprecated — use object format with defineSchema)