turbine-orm 0.9.2 → 0.11.0

package/dist/cjs/query/index.js

@@ -7,8 +7,11 @@
  * 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 = exports.postgresDialect = void 0;
+var dialect_js_1 = require("../dialect.js");
+Object.defineProperty(exports, "postgresDialect", { enumerable: true, get: function () { return dialect_js_1.postgresDialect; } });
 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/client.d.ts

@@ -22,6 +22,7 @@
  * ```
  */
 import pg from 'pg';
+import type { Dialect } from './dialect.js';
 import { type ErrorMessageMode } from './errors.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
 import { type DeferredQuery, QueryInterface, type QueryInterfaceOptions } from './query/index.js';
@@ -142,6 +143,8 @@ export interface TurbineConfig {
      * Default: `true`. Set to `false` as a nuclear kill switch.
      */
     sqlCache?: boolean;
+    /** SQL dialect implementation. Defaults to PostgreSQL. Internal Phase-1 seam for dialect packages. */
+    dialect?: Dialect;
 }
 /** Parameters passed to middleware functions */
 export interface MiddlewareParams {

package/dist/client.js

@@ -197,6 +197,7 @@ export class TurbineClient {
             warnOnUnlimited: config.warnOnUnlimited,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
+            dialect: config.dialect,
         };
         // Apply NotFoundError message redaction mode (default: safe — values are
         // stripped from messages to avoid leaking PII into error logs).

package/dist/dialect.d.ts

@@ -0,0 +1,61 @@
+/**
+ * turbine-orm — SQL dialect contract
+ *
+ * Phase-1 seam for future database packages. The current package remains
+ * PostgreSQL-native by default, but query generation now depends on this
+ * contract for the SQL primitives that vary across MySQL and SQLite.
+ */
+import type { SchemaMetadata } from './schema.js';
+export type DialectName = 'postgresql' | 'mysql' | 'sqlite' | (string & {});
+export interface Dialect {
+    /** Dialect identifier. */
+    readonly name: DialectName;
+    /** Parameter placeholder for the Nth value, using a 1-indexed public count. */
+    paramPlaceholder(index: number): string;
+    /** Quote a SQL identifier (table, column, cursor, alias). */
+    quoteIdentifier(name: string): string;
+    /** Escape a string literal body for SQL single-quoted strings. */
+    escapeStringLiteral(value: string): string;
+    /** Empty JSON array literal used as a fallback for to-many relations. */
+    readonly emptyJsonArrayLiteral: string;
+    /** JSON null literal/fallback for to-one relations. */
+    readonly nullJsonLiteral: string;
+    /** Build a JSON object expression from output keys and SQL expressions. */
+    buildJsonObject(pairs: [key: string, expr: string][]): string;
+    /** Build a JSON array aggregation expression with a dialect-specific empty-array fallback. */
+    buildJsonArrayAgg(jsonObjectExpr: string, orderBy?: string): string;
+    /** Whether INSERT/UPDATE/DELETE support RETURNING rows. */
+    readonly supportsReturning: boolean;
+    /** Whether native ILIKE is supported. */
+    readonly supportsILike: boolean;
+    /** Build a case-insensitive LIKE equivalent. */
+    buildInsensitiveLike(column: string, paramRef: string): string;
+    /** JSON operator support level for this dialect. */
+    readonly jsonPathSupport: 'native' | 'function' | 'limited';
+    /** Build a JSON containment check. */
+    buildJsonContains(column: string, paramRef: string): string;
+    /** Build a JSON path text extraction expression. */
+    buildJsonPathExtract(column: string, pathParamRef: string): string;
+    /** Build a correlation clause across single or composite keys. */
+    buildCorrelation(leftRef: string, leftColumns: string | string[], rightRef: string, rightColumns: string | string[]): string;
+    /** Type mapping hook for code generation. */
+    typeToTypeScript(dialectType: string, nullable: boolean): string;
+    /** Optional array-cast hook for bulk insert implementations. */
+    arrayType?(baseType: string): string;
+}
+export interface DialectIntrospector {
+    introspect(options: IntrospectOptions): Promise<SchemaMetadata>;
+}
+export interface IntrospectOptions {
+    connectionString: string;
+    schema?: string;
+    include?: string[];
+    exclude?: string[];
+}
+export interface DialectMigrator {
+    acquireLock(lockId: number): Promise<boolean>;
+    releaseLock(lockId: number): Promise<void>;
+}
+/** PostgreSQL implementation of the dialect contract. */
+export declare const postgresDialect: Dialect;
+//# sourceMappingURL=dialect.d.ts.map

package/dist/dialect.js

@@ -0,0 +1,55 @@
+/**
+ * turbine-orm — SQL dialect contract
+ *
+ * Phase-1 seam for future database packages. The current package remains
+ * PostgreSQL-native by default, but query generation now depends on this
+ * contract for the SQL primitives that vary across MySQL and SQLite.
+ */
+/** PostgreSQL implementation of the dialect contract. */
+export const postgresDialect = {
+    name: 'postgresql',
+    supportsReturning: true,
+    supportsILike: true,
+    jsonPathSupport: 'native',
+    emptyJsonArrayLiteral: "'[]'::json",
+    nullJsonLiteral: 'NULL',
+    paramPlaceholder(index) {
+        return `$${index}`;
+    },
+    quoteIdentifier(name) {
+        return `"${name.replace(/"/g, '""')}"`;
+    },
+    escapeStringLiteral(value) {
+        return value.replace(/'/g, "''");
+    },
+    buildJsonObject(pairs) {
+        const args = pairs.map(([key, expr]) => `'${this.escapeStringLiteral(key)}', ${expr}`);
+        return `json_build_object(${args.join(', ')})`;
+    },
+    buildJsonArrayAgg(jsonObjectExpr, orderBy) {
+        const suffix = orderBy ? ` ${orderBy}` : '';
+        return `COALESCE(json_agg(${jsonObjectExpr}${suffix}), ${this.emptyJsonArrayLiteral})`;
+    },
+    buildInsensitiveLike(column, paramRef) {
+        return `${column} ILIKE ${paramRef}`;
+    },
+    buildJsonContains(column, paramRef) {
+        return `${column} @> ${paramRef}::jsonb`;
+    },
+    buildJsonPathExtract(column, pathParamRef) {
+        return `${column} #>> ${pathParamRef}::text[]`;
+    },
+    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}.${this.quoteIdentifier(col)} = ${rightRef}.${this.quoteIdentifier(rightCols[i])}`)
+            .join(' AND ');
+    },
+    typeToTypeScript(_dialectType, _nullable) {
+        // Existing PostgreSQL type mapping remains in schema.ts/generate.ts for now.
+        // This hook is the package boundary MySQL/SQLite implementations will fill.
+        return 'unknown';
+    },
+};
+//# sourceMappingURL=dialect.js.map

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,18 @@
  * 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 type { Dialect, DialectIntrospector, DialectMigrator, DialectName, IntrospectOptions as DialectIntrospectOptions, } from './dialect.js';
+export { postgresDialect } from './dialect.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/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,8 +32,10 @@
  * await db.disconnect();
  * ```
  */
+export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
 // Client
 export { TransactionClient, TurbineClient, } from './client.js';
+export { postgresDialect } from './dialect.js';
 // Error types
 export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, PipelineError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
 // Code generation
@@ -45,7 +47,7 @@ export { executePipeline, pipelineSupported } from './pipeline.js';
 // Query builder
 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)

package/dist/introspect.js

@@ -66,13 +66,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
@@ -153,14 +156,22 @@ export 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();
@@ -187,17 +198,25 @@ export 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();
@@ -209,10 +228,17 @@ export 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
-                ? snakeToCamel(fk.sourceColumn.replace(/_id$/, ''))
+                ? fk.sourceColumns.length === 1
+                    ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
+                    : snakeToCamel(fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, ''))
                 : singularize(snakeToCamel(fk.targetTable));
             if (!relationsByTable.has(fk.sourceTable))
                 relationsByTable.set(fk.sourceTable, {});
@@ -221,13 +247,15 @@ export 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
-                ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumn.replace(/_id$/, '')}`)
+                ? fk.sourceColumns.length === 1
+                    ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
+                    : snakeToCamel(`${fk.sourceTable}_by_${fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, '')}`)
                 : snakeToCamel(fk.sourceTable);
             if (!relationsByTable.has(fk.targetTable))
                 relationsByTable.set(fk.targetTable, {});
@@ -236,8 +264,8 @@ export 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/query/builder.d.ts

@@ -11,6 +11,7 @@
  * metadata — nothing is hardcoded.
  */
 import type pg from 'pg';
+import type { Dialect } from '../dialect.js';
 import type { SchemaMetadata } from '../schema.js';
 import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause, WithResult } from './types.js';
 export interface DeferredQuery<T> {
@@ -64,6 +65,8 @@ export interface QueryInterfaceOptions {
      * Default: `true`. Set to `false` as a nuclear kill switch.
      */
     sqlCache?: boolean;
+    /** SQL dialect implementation. Defaults to PostgreSQL. */
+    dialect?: Dialect;
 }
 export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
@@ -77,6 +80,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly warnOnUnlimited;
     private readonly preparedStatementsEnabled;
     private readonly sqlCacheEnabled;
+    private readonly dialect;
     /**
      * Tracks tables that have already triggered an unlimited-query warning so
      * the user is not spammed once per row. Per-instance state — each
@@ -95,6 +99,10 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     /** Tracks tables that have already triggered a deep-with warning (one-time) */
     private readonly deepWithWarned;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /** Quote an identifier through the active SQL dialect. */
+    private q;
+    /** Return the active dialect's placeholder for a 1-indexed parameter position. */
+    private p;
     /**
      * Return cache hit/miss statistics for this QueryInterface instance.
      * Useful for monitoring and benchmarking.
@@ -433,7 +441,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * 8. **Parameter threading:** All user-supplied values (where filters, limit) are
      *    pushed to the shared `params` array with `$N` placeholders. No string
      *    interpolation of user data ever occurs -- all identifiers go through
-     *    `quoteIdent()` and all values are parameterized.
+     *    `this.q()` and all values are parameterized.
      *
      * ### Example output (hasMany with nested relation)
      * ```sql