turbine-orm 0.9.2 → 0.11.0

package/dist/query/builder.js

@@ -10,9 +10,10 @@
  * Schema-driven: all column names, types, and relations come from introspected
  * metadata — nothing is hardcoded.
  */
+import { postgresDialect } from '../dialect.js';
 import { CircularRelationError, NotFoundError, RelationError, TimeoutError, ValidationError, wrapPgError, } from '../errors.js';
 import { camelToSnake, snakeToCamel } from '../schema.js';
-import { escapeLike, escSingleQuote, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
+import { escapeLike, LRUCache, OPERATOR_KEYS, sqlToPreparedName } from './utils.js';
 // ---------------------------------------------------------------------------
 // Internal detection helpers — used by QueryInterface
 // ---------------------------------------------------------------------------
@@ -96,6 +97,7 @@ function findArrayUniqueKey(value) {
     }
     return null;
 }
+// biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
 export class QueryInterface {
     pool;
     table;
@@ -108,6 +110,7 @@ export class QueryInterface {
     warnOnUnlimited;
     preparedStatementsEnabled;
     sqlCacheEnabled;
+    dialect;
     /**
      * Tracks tables that have already triggered an unlimited-query warning so
      * the user is not spammed once per row. Per-instance state — each
@@ -142,6 +145,7 @@ export class QueryInterface {
         this.warnOnUnlimited = options?.warnOnUnlimited !== false;
         this.preparedStatementsEnabled = options?.preparedStatements ?? true;
         this.sqlCacheEnabled = options?.sqlCache !== false;
+        this.dialect = options?.dialect ?? postgresDialect;
         // Pre-compute column type lookup maps (TASK-26)
         this.columnPgTypeMap = new Map();
         this.columnArrayTypeMap = new Map();
@@ -150,6 +154,14 @@ export class QueryInterface {
             this.columnArrayTypeMap.set(col.name, col.pgArrayType);
         }
     }
+    /** Quote an identifier through the active SQL dialect. */
+    q(name) {
+        return this.dialect.quoteIdentifier(name);
+    }
+    /** Return the active dialect's placeholder for a 1-indexed parameter position. */
+    p(index) {
+        return this.dialect.paramPlaceholder(index);
+    }
     /**
      * Return cache hit/miss statistics for this QueryInterface instance.
      * Useful for monitoring and benchmarking.
@@ -258,6 +270,7 @@ export 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);
@@ -265,6 +278,7 @@ export 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;
@@ -285,11 +299,11 @@ export class QueryInterface {
         // Simple path: plain equality, no operators/null/OR
         if (!args.with && isSimpleWhere) {
             const entry = this.acquireSql(ck, () => {
-                const qt = quoteIdent(this.table);
+                const qt = this.q(this.table);
                 const tempParams = whereKeys.map((k) => whereObj[k]);
-                const whereClauses = whereKeys.map((k, i) => `${this.toSqlColumn(k)} = $${i + 1}`);
+                const whereClauses = whereKeys.map((k, i) => `${this.toSqlColumn(k)} = ${this.p(i + 1)}`);
                 const whereSql = whereClauses.length > 0 ? ` WHERE ${whereClauses.join(' AND ')}` : '';
-                const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ') : `${qt}.*`;
+                const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
                 void tempParams; // params are positional, SQL is value-invariant
                 return `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
             });
@@ -314,8 +328,8 @@ export class QueryInterface {
                 const freshParams = [];
                 const clause = this.buildWhereClause(whereObj, freshParams);
                 const whereSql = clause ? ` WHERE ${clause}` : '';
-                const qt = quoteIdent(this.table);
-                const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ') : `${qt}.*`;
+                const qt = this.q(this.table);
+                const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
                 return `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
             });
             // Collect params
@@ -341,7 +355,7 @@ export class QueryInterface {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             const selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
-            return `SELECT ${selectClause} FROM ${quoteIdent(this.table)}${whereSql} LIMIT 1`;
+            return `SELECT ${selectClause} FROM ${this.q(this.table)}${whereSql} LIMIT 1`;
         });
         // Collect params in exact build order: where first, then with-clause relations
         this.collectWhereParams(whereObj, params);
@@ -360,6 +374,7 @@ export 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
@@ -417,6 +432,7 @@ export 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(',') : '*';
@@ -450,7 +466,7 @@ export class QueryInterface {
                     return { sql: clause ? ` WHERE ${clause}` : '' };
                 })()
                 : { sql: '' };
-            const qt = quoteIdent(this.table);
+            const qt = this.q(this.table);
             let distinctPrefix = '';
             if (args?.distinct && args.distinct.length > 0) {
                 const distinctCols = args.distinct.map((k) => this.toSqlColumn(k));
@@ -461,7 +477,7 @@ export class QueryInterface {
                 selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
             }
             else if (columnsList) {
-                selectClause = columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ');
+                selectClause = columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ');
             }
             else {
                 selectClause = `${qt}.*`;
@@ -475,7 +491,7 @@ export class QueryInterface {
                         const dir = args.orderBy?.[k] ?? 'asc';
                         const op = dir === 'desc' ? '<' : '>';
                         freshParams.push(v);
-                        return `${qt}.${col} ${op} $${freshParams.length}`;
+                        return `${qt}.${col} ${op} ${this.p(freshParams.length)}`;
                     });
                     if (freshWhereSql) {
                         sql += ` AND ${cursorConditions.join(' AND ')}`;
@@ -490,11 +506,11 @@ export class QueryInterface {
             }
             if (effectiveLimit !== undefined) {
                 freshParams.push(Number(effectiveLimit));
-                sql += ` LIMIT $${freshParams.length}`;
+                sql += ` LIMIT ${this.p(freshParams.length)}`;
             }
             if (args?.offset !== undefined) {
                 freshParams.push(Number(args.offset));
-                sql += ` OFFSET $${freshParams.length}`;
+                sql += ` OFFSET ${this.p(freshParams.length)}`;
             }
             return sql;
         });
@@ -560,6 +576,7 @@ export 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;
@@ -581,7 +598,7 @@ export class QueryInterface {
         // Acquire a dedicated connection — cursors require a single connection in a transaction
         const client = await this.pool.connect();
         const cursorName = `turbine_cursor_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-        const quotedCursor = quoteIdent(cursorName);
+        const quotedCursor = this.q(cursorName);
         try {
             await client.query('BEGIN');
             await client.query(`DECLARE ${quotedCursor} NO SCROLL CURSOR FOR ${deferred.sql}`, deferred.params);
@@ -616,6 +633,7 @@ export 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);
@@ -623,6 +641,7 @@ export 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 };
@@ -640,6 +659,7 @@ export 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);
@@ -647,6 +667,7 @@ export 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 {
@@ -669,6 +690,7 @@ export 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);
@@ -676,6 +698,7 @@ export 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 {
@@ -709,8 +732,8 @@ export class QueryInterface {
         const entries = Object.entries(args.data).filter(([, v]) => v !== undefined);
         const columns = entries.map(([k]) => this.toSqlColumn(k));
         const params = entries.map(([, v]) => v);
-        const placeholders = entries.map((_, i) => `$${i + 1}`);
-        const sql = `INSERT INTO ${quoteIdent(this.table)} (${columns.join(', ')}) VALUES (${placeholders.join(', ')}) RETURNING *`;
+        const placeholders = entries.map((_, i) => `${this.p(i + 1)}`);
+        const sql = `INSERT INTO ${this.q(this.table)} (${columns.join(', ')}) VALUES (${placeholders.join(', ')}) RETURNING *`;
         return {
             sql,
             params,
@@ -739,7 +762,7 @@ export class QueryInterface {
         });
     }
     buildCreateMany(args) {
-        const qt = quoteIdent(this.table);
+        const qt = this.q(this.table);
         if (args.data.length === 0) {
             return {
                 sql: `SELECT * FROM ${qt} WHERE false`,
@@ -760,8 +783,8 @@ export class QueryInterface {
         }
         // Use actual Postgres types for array casts
         const typeCasts = columns.map((col) => this.getColumnArrayType(col));
-        const unnestArgs = columnArrays.map((_, i) => `$${i + 1}::${typeCasts[i]}`);
-        const quotedColumns = columns.map((c) => quoteIdent(c));
+        const unnestArgs = columnArrays.map((_, i) => `${this.p(i + 1)}::${typeCasts[i]}`);
+        const quotedColumns = columns.map((c) => this.q(c));
         let sql = `INSERT INTO ${qt} (${quotedColumns.join(', ')}) SELECT * FROM UNNEST(${unnestArgs.join(', ')})`;
         // skipDuplicates: add ON CONFLICT DO NOTHING
         if (args.skipDuplicates) {
@@ -799,7 +822,7 @@ export class QueryInterface {
             const whereClause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
             this.assertMutationHasPredicate('update', whereSql, args.allowFullTableScan);
-            return `UPDATE ${quoteIdent(this.table)} SET ${setClauses.join(', ')}${whereSql} RETURNING *`;
+            return `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql} RETURNING *`;
         });
         // On cache hit, validate predicate
         if (whereFp === '') {
@@ -848,7 +871,7 @@ export class QueryInterface {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             this.assertMutationHasPredicate('delete', whereSql, args.allowFullTableScan);
-            return `DELETE FROM ${quoteIdent(this.table)}${whereSql} RETURNING *`;
+            return `DELETE FROM ${this.q(this.table)}${whereSql} RETURNING *`;
         });
         // On cache hit, still validate the predicate
         if (whereFp === '') {
@@ -888,7 +911,7 @@ export class QueryInterface {
         const createEntries = Object.entries(args.create).filter(([, v]) => v !== undefined);
         const columns = createEntries.map(([k]) => this.toSqlColumn(k));
         const createParams = createEntries.map(([, v]) => v);
-        const placeholders = createEntries.map((_, i) => `$${i + 1}`);
+        const placeholders = createEntries.map((_, i) => `${this.p(i + 1)}`);
         // The conflict target comes from `where` keys — must be unique/PK columns
         const conflictKeys = Object.keys(args.where).filter((k) => args.where[k] !== undefined);
         const conflictColumns = conflictKeys.map((k) => this.toSqlColumn(k));
@@ -896,13 +919,13 @@ export class QueryInterface {
         const updateEntries = Object.entries(args.update).filter(([, v]) => v !== undefined);
         let paramIdx = createParams.length + 1;
         const setClauses = updateEntries.map(([k]) => {
-            const clause = `${this.toSqlColumn(k)} = $${paramIdx}`;
+            const clause = `${this.toSqlColumn(k)} = ${this.p(paramIdx)}`;
             paramIdx++;
             return clause;
         });
         const updateParams = updateEntries.map(([, v]) => v);
         const params = [...createParams, ...updateParams];
-        const sql = `INSERT INTO ${quoteIdent(this.table)} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})` +
+        const sql = `INSERT INTO ${this.q(this.table)} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})` +
             ` ON CONFLICT (${conflictColumns.join(', ')}) DO UPDATE SET ${setClauses.join(', ')}` +
             ` RETURNING *`;
         return {
@@ -947,7 +970,7 @@ export class QueryInterface {
             const whereClause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
             this.assertMutationHasPredicate('updateMany', whereSql, args.allowFullTableScan);
-            return `UPDATE ${quoteIdent(this.table)} SET ${setClauses.join(', ')}${whereSql}`;
+            return `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql}`;
         });
         if (whereFp === '') {
             this.assertMutationHasPredicate('updateMany', '', args.allowFullTableScan);
@@ -982,7 +1005,7 @@ export class QueryInterface {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             this.assertMutationHasPredicate('deleteMany', whereSql, args.allowFullTableScan);
-            return `DELETE FROM ${quoteIdent(this.table)}${whereSql}`;
+            return `DELETE FROM ${this.q(this.table)}${whereSql}`;
         });
         if (whereFp === '') {
             this.assertMutationHasPredicate('deleteMany', '', args.allowFullTableScan);
@@ -1015,7 +1038,7 @@ export class QueryInterface {
             const freshParams = [];
             const clause = args?.where ? this.buildWhereClause(whereObj, freshParams) : null;
             const whereSql = clause ? ` WHERE ${clause}` : '';
-            return `SELECT COUNT(*)::int AS count FROM ${quoteIdent(this.table)}${whereSql}`;
+            return `SELECT COUNT(*)::int AS count FROM ${this.q(this.table)}${whereSql}`;
         });
         if (args?.where) {
             this.collectWhereParams(whereObj, params);
@@ -1048,7 +1071,7 @@ export class QueryInterface {
             }
         }
         const groupColsRaw = args.by.map((k) => this.toColumn(k));
-        const groupCols = groupColsRaw.map((c) => quoteIdent(c));
+        const groupCols = groupColsRaw.map((c) => this.q(c));
         const { sql: whereSql, params } = args.where ? this.buildWhere(args.where) : { sql: '', params: [] };
         // Build SELECT expressions: group-by columns + aggregate functions
         const selectExprs = [...groupCols];
@@ -1062,7 +1085,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._sum)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`SUM(${quoteIdent(col)}) AS ${quoteIdent(`_sum_${col}`)}`);
+                    selectExprs.push(`SUM(${this.q(col)}) AS ${this.q(`_sum_${col}`)}`);
                 }
             }
         }
@@ -1071,7 +1094,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._avg)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`AVG(${quoteIdent(col)})::float AS ${quoteIdent(`_avg_${col}`)}`);
+                    selectExprs.push(`AVG(${this.q(col)})::float AS ${this.q(`_avg_${col}`)}`);
                 }
             }
         }
@@ -1080,7 +1103,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._min)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`MIN(${quoteIdent(col)}) AS ${quoteIdent(`_min_${col}`)}`);
+                    selectExprs.push(`MIN(${this.q(col)}) AS ${this.q(`_min_${col}`)}`);
                 }
             }
         }
@@ -1089,11 +1112,11 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._max)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`MAX(${quoteIdent(col)}) AS ${quoteIdent(`_max_${col}`)}`);
+                    selectExprs.push(`MAX(${this.q(col)}) AS ${this.q(`_max_${col}`)}`);
                 }
             }
         }
-        let sql = `SELECT ${selectExprs.join(', ')} FROM ${quoteIdent(this.table)}${whereSql} GROUP BY ${groupCols.join(', ')}`;
+        let sql = `SELECT ${selectExprs.join(', ')} FROM ${this.q(this.table)}${whereSql} GROUP BY ${groupCols.join(', ')}`;
         // ORDER BY
         if (args.orderBy) {
             sql += ` ORDER BY ${this.buildOrderBy(args.orderBy)}`;
@@ -1201,7 +1224,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._count)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`COUNT(${quoteIdent(col)})::int AS ${quoteIdent(`_count_${col}`)}`);
+                    selectExprs.push(`COUNT(${this.q(col)})::int AS ${this.q(`_count_${col}`)}`);
                 }
             }
         }
@@ -1210,7 +1233,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._sum)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`SUM(${quoteIdent(col)}) AS ${quoteIdent(`_sum_${col}`)}`);
+                    selectExprs.push(`SUM(${this.q(col)}) AS ${this.q(`_sum_${col}`)}`);
                 }
             }
         }
@@ -1219,7 +1242,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._avg)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`AVG(${quoteIdent(col)})::float AS ${quoteIdent(`_avg_${col}`)}`);
+                    selectExprs.push(`AVG(${this.q(col)})::float AS ${this.q(`_avg_${col}`)}`);
                 }
             }
         }
@@ -1228,7 +1251,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._min)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`MIN(${quoteIdent(col)}) AS ${quoteIdent(`_min_${col}`)}`);
+                    selectExprs.push(`MIN(${this.q(col)}) AS ${this.q(`_min_${col}`)}`);
                 }
             }
         }
@@ -1237,14 +1260,14 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._max)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`MAX(${quoteIdent(col)}) AS ${quoteIdent(`_max_${col}`)}`);
+                    selectExprs.push(`MAX(${this.q(col)}) AS ${this.q(`_max_${col}`)}`);
                 }
             }
         }
         if (selectExprs.length === 0) {
             selectExprs.push('COUNT(*)::int AS _count');
         }
-        const sql = `SELECT ${selectExprs.join(', ')} FROM ${quoteIdent(this.table)}${whereSql}`;
+        const sql = `SELECT ${selectExprs.join(', ')} FROM ${this.q(this.table)}${whereSql}`;
         return {
             sql,
             params,
@@ -1361,7 +1384,7 @@ export class QueryInterface {
     }
     /** Convert camelCase field name to a double-quoted SQL identifier */
     toSqlColumn(field) {
-        return quoteIdent(this.toColumn(field));
+        return this.q(this.toColumn(field));
     }
     /**
      * Build a single SET clause entry for update/updateMany.
@@ -1394,7 +1417,7 @@ export class QueryInterface {
                 const opValue = v[op];
                 if (op === 'set') {
                     params.push(opValue);
-                    return `${col} = $${params.length}`;
+                    return `${col} = ${this.p(params.length)}`;
                 }
                 // Arithmetic operators: must be finite numbers
                 if (typeof opValue !== 'number' || !Number.isFinite(opValue)) {
@@ -1402,19 +1425,19 @@ export class QueryInterface {
                 }
                 if (op === 'increment') {
                     params.push(opValue);
-                    return `${col} = ${col} + $${params.length}`;
+                    return `${col} = ${col} + ${this.p(params.length)}`;
                 }
                 if (op === 'decrement') {
                     params.push(opValue);
-                    return `${col} = ${col} - $${params.length}`;
+                    return `${col} = ${col} - ${this.p(params.length)}`;
                 }
                 if (op === 'multiply') {
                     params.push(opValue);
-                    return `${col} = ${col} * $${params.length}`;
+                    return `${col} = ${col} * ${this.p(params.length)}`;
                 }
                 if (op === 'divide') {
                     params.push(opValue);
-                    return `${col} = ${col} / $${params.length}`;
+                    return `${col} = ${col} / ${this.p(params.length)}`;
                 }
             }
             // Fall through: multi-key objects or non-operator single-key objects
@@ -1422,7 +1445,7 @@ export class QueryInterface {
         }
         // Plain value (including null, Date, Buffer, arrays, JSON objects)
         params.push(value);
-        return `${col} = $${params.length}`;
+        return `${col} = ${this.p(params.length)}`;
     }
     // =========================================================================
     // Fingerprinting — value-invariant shape keys for SQL cache lookup
@@ -1945,7 +1968,7 @@ export class QueryInterface {
                 }
             }
             const rawColumn = this.toColumn(key);
-            const column = quoteIdent(rawColumn);
+            const column = this.q(rawColumn);
             // Handle null → IS NULL
             if (value === null) {
                 andClauses.push(`${column} IS NULL`);
@@ -1995,7 +2018,7 @@ export class QueryInterface {
             }
             // Plain equality
             params.push(value);
-            andClauses.push(`${column} = $${params.length}`);
+            andClauses.push(`${column} = ${this.p(params.length)}`);
         }
         if (andClauses.length === 0)
             return null;
@@ -2010,18 +2033,18 @@ export class QueryInterface {
         const targetMeta = this.schema.tables[targetTable];
         if (!targetMeta)
             return null;
-        const qt = quoteIdent(targetTable);
-        const qSelf = quoteIdent(this.table);
+        const qt = this.q(targetTable);
+        const qSelf = this.q(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}.${quoteIdent(relDef.foreignKey)} = ${qSelf}.${quoteIdent(relDef.referenceKey)}`;
+            correlation = this.dialect.buildCorrelation(qt, relDef.foreignKey, qSelf, relDef.referenceKey);
         }
         else {
             // belongsTo: parent.fk = child.pk
-            correlation = `${qt}.${quoteIdent(relDef.referenceKey)} = ${qSelf}.${quoteIdent(relDef.foreignKey)}`;
+            correlation = this.dialect.buildCorrelation(qt, relDef.referenceKey, qSelf, relDef.foreignKey);
         }
         // "some": EXISTS (SELECT 1 FROM target WHERE correlation AND filter)
         if (filterObj.some !== undefined) {
@@ -2058,13 +2081,17 @@ export class QueryInterface {
         const meta = this.schema.tables[targetTable];
         if (!meta)
             return null;
-        const qt = quoteIdent(targetTable);
+        const qt = this.q(targetTable);
         const conditions = [];
         for (const [field, value] of Object.entries(subWhere)) {
             if (value === undefined)
                 continue;
             const col = meta.columnMap[field] ?? camelToSnake(field);
-            const qCol = `${qt}.${quoteIdent(col)}`;
+            if (!meta.allColumns.includes(col)) {
+                throw new ValidationError(`[turbine] Unknown field "${field}" in relation filter for table "${targetTable}". ` +
+                    `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
+            }
+            const qCol = `${qt}.${this.q(col)}`;
             if (value === null) {
                 conditions.push(`${qCol} IS NULL`);
                 continue;
@@ -2075,7 +2102,7 @@ export class QueryInterface {
                 continue;
             }
             params.push(value);
-            conditions.push(`${qCol} = $${params.length}`);
+            conditions.push(`${qCol} = ${this.p(params.length)}`);
         }
         return conditions.length > 0 ? conditions.join(' AND ') : null;
     }
@@ -2087,19 +2114,19 @@ export class QueryInterface {
         const clauses = [];
         if (op.gt !== undefined) {
             params.push(op.gt);
-            clauses.push(`${column} > $${params.length}`);
+            clauses.push(`${column} > ${this.p(params.length)}`);
         }
         if (op.gte !== undefined) {
             params.push(op.gte);
-            clauses.push(`${column} >= $${params.length}`);
+            clauses.push(`${column} >= ${this.p(params.length)}`);
         }
         if (op.lt !== undefined) {
             params.push(op.lt);
-            clauses.push(`${column} < $${params.length}`);
+            clauses.push(`${column} < ${this.p(params.length)}`);
         }
         if (op.lte !== undefined) {
             params.push(op.lte);
-            clauses.push(`${column} <= $${params.length}`);
+            clauses.push(`${column} <= ${this.p(params.length)}`);
         }
         if (op.not !== undefined) {
             if (op.not === null) {
@@ -2107,30 +2134,29 @@ export class QueryInterface {
             }
             else {
                 params.push(op.not);
-                clauses.push(`${column} != $${params.length}`);
+                clauses.push(`${column} != ${this.p(params.length)}`);
             }
         }
         if (op.in !== undefined) {
             params.push(op.in);
-            clauses.push(`${column} = ANY($${params.length})`);
+            clauses.push(`${column} = ANY(${this.p(params.length)})`);
         }
         if (op.notIn !== undefined) {
             params.push(op.notIn);
-            clauses.push(`${column} != ALL($${params.length})`);
+            clauses.push(`${column} != ALL(${this.p(params.length)})`);
         }
-        // Use ILIKE for case-insensitive mode, LIKE otherwise
-        const likeOp = op.mode === 'insensitive' ? 'ILIKE' : 'LIKE';
+        const buildLikeClause = (paramRef) => op.mode === 'insensitive' ? this.dialect.buildInsensitiveLike(column, paramRef) : `${column} LIKE ${paramRef}`;
         if (op.contains !== undefined) {
             params.push(`%${escapeLike(op.contains)}%`);
-            clauses.push(`${column} ${likeOp} $${params.length} ESCAPE '\\'`);
+            clauses.push(`${buildLikeClause(this.p(params.length))} ESCAPE '\\'`);
         }
         if (op.startsWith !== undefined) {
             params.push(`${escapeLike(op.startsWith)}%`);
-            clauses.push(`${column} ${likeOp} $${params.length} ESCAPE '\\'`);
+            clauses.push(`${buildLikeClause(this.p(params.length))} ESCAPE '\\'`);
         }
         if (op.endsWith !== undefined) {
             params.push(`%${escapeLike(op.endsWith)}`);
-            clauses.push(`${column} ${likeOp} $${params.length} ESCAPE '\\'`);
+            clauses.push(`${buildLikeClause(this.p(params.length))} ESCAPE '\\'`);
         }
         return clauses;
     }
@@ -2290,8 +2316,8 @@ export class QueryInterface {
         if (!meta)
             throw new ValidationError(`[turbine] Unknown table "${table}"`);
         const cols = columnsList ?? meta.allColumns;
-        const qtbl = quoteIdent(table);
-        const baseCols = cols.map((col) => `${qtbl}.${quoteIdent(col)}`).join(', ');
+        const qtbl = this.q(table);
+        const baseCols = cols.map((col) => `${qtbl}.${this.q(col)}`).join(', ');
         const relationSelects = [];
         const aliasCounter = { n: 0 };
         for (const [relName, relSpec] of Object.entries(withClause)) {
@@ -2302,7 +2328,7 @@ export class QueryInterface {
             }
             // The main table is not aliased, so pass table name as parentRef
             const subquery = this.buildRelationSubquery(relDef, relSpec, params, table, aliasCounter, depth, path);
-            relationSelects.push(`(${subquery}) AS ${quoteIdent(relName)}`);
+            relationSelects.push(`(${subquery}) AS ${this.q(relName)}`);
         }
         return [baseCols, ...relationSelects].join(', ');
     }
@@ -2364,7 +2390,7 @@ export class QueryInterface {
      * 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
@@ -2428,8 +2454,11 @@ export class QueryInterface {
                 .map(([k]) => targetMeta.columnMap[k] ?? camelToSnake(k)));
             targetColumns = targetMeta.allColumns.filter((col) => !omittedFields.has(col));
         }
-        // Build json_build_object pairs for resolved columns
-        const jsonPairs = targetColumns.map((col) => `'${escSingleQuote(targetMeta.reverseColumnMap[col] ?? snakeToCamel(col))}', ${alias}.${quoteIdent(col)}`);
+        // Build JSON object pairs for resolved columns
+        const jsonPairs = targetColumns.map((col) => [
+            targetMeta.reverseColumnMap[col] ?? snakeToCamel(col),
+            `${alias}.${this.q(col)}`,
+        ]);
         // Determine if this hasMany will take the wrapped subquery path (LIMIT or ORDER BY).
         // When wrapping, nested relations are built in the wrapped path referencing innerAlias,
         // so we must NOT build them here (they would push orphaned params).
@@ -2445,14 +2474,14 @@ export class QueryInterface {
                 // Recursively build nested subquery, passing THIS alias as the parent reference
                 const nestedSubquery = this.buildRelationSubquery(nestedRelDef, nestedSpec, params, alias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name]);
                 // Use '[]'::json for hasMany (empty array), NULL for belongsTo/hasOne (no object)
-                const fallback = nestedRelDef.type === 'hasMany' ? "'[]'::json" : 'NULL';
-                jsonPairs.push(`'${escSingleQuote(nestedRelName)}', COALESCE((${nestedSubquery}), ${fallback})`);
+                const fallback = nestedRelDef.type === 'hasMany' ? this.dialect.emptyJsonArrayLiteral : this.dialect.nullJsonLiteral;
+                jsonPairs.push([nestedRelName, `COALESCE((${nestedSubquery}), ${fallback})`]);
             }
         }
-        const jsonObj = `json_build_object(${jsonPairs.join(', ')})`;
+        const jsonObj = this.dialect.buildJsonObject(jsonPairs);
         // Quote parent ref — can be a table name or auto-generated alias
-        const qParent = quoteIdent(parentRef);
-        const qTarget = quoteIdent(targetTable);
+        const qParent = this.q(parentRef);
+        const qTarget = this.q(targetTable);
         // Build ORDER BY for json_agg
         let orderClause = '';
         if (spec !== true && spec.orderBy) {
@@ -2463,7 +2492,7 @@ export class QueryInterface {
                     throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
                 }
                 const safeDir = dir.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-                return `${alias}.${quoteIdent(col)} ${safeDir}`;
+                return `${alias}.${this.q(col)} ${safeDir}`;
             })
                 .join(', ');
             orderClause = ` ORDER BY ${orders}`;
@@ -2471,12 +2500,13 @@ export 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}.${quoteIdent(relDef.referenceKey)} = ${qParent}.${quoteIdent(relDef.foreignKey)}`;
+            whereClause = this.dialect.buildCorrelation(alias, relDef.referenceKey, qParent, relDef.foreignKey);
         }
         else {
-            whereClause = `${alias}.${quoteIdent(relDef.foreignKey)} = ${qParent}.${quoteIdent(relDef.referenceKey)}`;
+            whereClause = this.dialect.buildCorrelation(alias, relDef.foreignKey, qParent, relDef.referenceKey);
         }
         // Additional filters — properly parameterized
         if (spec !== true && spec.where) {
@@ -2486,14 +2516,14 @@ export class QueryInterface {
                     throw new ValidationError(`[turbine] Unknown column "${k}" in where for table "${targetTable}"`);
                 }
                 params.push(v);
-                whereClause += ` AND ${alias}.${quoteIdent(col)} = $${params.length}`;
+                whereClause += ` AND ${alias}.${this.q(col)} = ${this.p(params.length)}`;
             }
         }
         // LIMIT
         let limitClause = '';
         if (spec !== true && spec.limit) {
             params.push(Number(spec.limit));
-            limitClause = ` LIMIT $${params.length}`;
+            limitClause = ` LIMIT ${this.p(params.length)}`;
         }
         if (relDef.type === 'hasMany') {
             // When LIMIT or ORDER BY is used, wrap in a subquery so LIMIT applies to rows
@@ -2502,9 +2532,12 @@ export class QueryInterface {
                 const innerAlias = `${alias}i`;
                 // Rewrite: SELECT json_agg(json_build_object(...)) FROM (SELECT * FROM table WHERE ... ORDER BY ... LIMIT N) AS alias
                 // Inner SELECT always needs all columns for WHERE/ORDER to work; json_build_object filters later
-                const innerSql = `SELECT ${targetMeta.allColumns.map((c) => `${alias}.${quoteIdent(c)}`).join(', ')} FROM ${qTarget} ${alias} WHERE ${whereClause}${orderClause}${limitClause}`;
+                const innerSql = `SELECT ${targetMeta.allColumns.map((c) => `${alias}.${this.q(c)}`).join(', ')} FROM ${qTarget} ${alias} WHERE ${whereClause}${orderClause}${limitClause}`;
                 // For the json_build_object, reference the inner alias — only include resolved columns
-                const innerJsonPairs = targetColumns.map((col) => `'${escSingleQuote(targetMeta.reverseColumnMap[col] ?? snakeToCamel(col))}', ${innerAlias}.${quoteIdent(col)}`);
+                const innerJsonPairs = targetColumns.map((col) => [
+                    targetMeta.reverseColumnMap[col] ?? snakeToCamel(col),
+                    `${innerAlias}.${this.q(col)}`,
+                ]);
                 // Build nested relation subqueries referencing innerAlias
                 if (spec !== true && spec.with) {
                     for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
@@ -2514,14 +2547,14 @@ export class QueryInterface {
                                 `Available: ${Object.keys(targetMeta.relations).join(', ')}`);
                         }
                         const nestedSub = this.buildRelationSubquery(nestedRelDef, nestedSpec, params, innerAlias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name]);
-                        const fallback = nestedRelDef.type === 'hasMany' ? "'[]'::json" : 'NULL';
-                        innerJsonPairs.push(`'${escSingleQuote(nestedRelName)}', COALESCE((${nestedSub}), ${fallback})`);
+                        const fallback = nestedRelDef.type === 'hasMany' ? this.dialect.emptyJsonArrayLiteral : this.dialect.nullJsonLiteral;
+                        innerJsonPairs.push([nestedRelName, `COALESCE((${nestedSub}), ${fallback})`]);
                     }
                 }
-                const innerJsonObj = `json_build_object(${innerJsonPairs.join(', ')})`;
-                return `SELECT COALESCE(json_agg(${innerJsonObj}), '[]'::json) FROM (${innerSql}) ${innerAlias}`;
+                const innerJsonObj = this.dialect.buildJsonObject(innerJsonPairs);
+                return `SELECT ${this.dialect.buildJsonArrayAgg(innerJsonObj)} FROM (${innerSql}) ${innerAlias}`;
             }
-            return `SELECT COALESCE(json_agg(${jsonObj}${orderClause}), '[]'::json) FROM ${qTarget} ${alias} WHERE ${whereClause}`;
+            return `SELECT ${this.dialect.buildJsonArrayAgg(jsonObj, orderClause.trim() || undefined)} FROM ${qTarget} ${alias} WHERE ${whereClause}`;
         }
         // belongsTo / hasOne — return single object
         return `SELECT ${jsonObj} FROM ${qTarget} ${alias} WHERE ${whereClause} LIMIT 1`;
@@ -2568,22 +2601,22 @@ export class QueryInterface {
             params.push(filter.path);
             const pathParam = params.length;
             params.push(String(filter.equals));
-            clauses.push(`${column} #>> $${pathParam}::text[] = $${params.length}`);
+            clauses.push(`${this.dialect.buildJsonPathExtract(column, this.p(pathParam))} = ${this.p(params.length)}`);
         }
         else if (filter.equals !== undefined) {
             // Containment equality: column @> $N::jsonb
             params.push(JSON.stringify(filter.equals));
-            clauses.push(`${column} @> $${params.length}::jsonb`);
+            clauses.push(this.dialect.buildJsonContains(column, this.p(params.length)));
         }
         if (filter.contains !== undefined) {
             // Containment: column @> $N::jsonb
             params.push(JSON.stringify(filter.contains));
-            clauses.push(`${column} @> $${params.length}::jsonb`);
+            clauses.push(this.dialect.buildJsonContains(column, this.p(params.length)));
         }
         if (filter.hasKey !== undefined) {
             // Key existence: column ? $N
             params.push(filter.hasKey);
-            clauses.push(`${column} ? $${params.length}`);
+            clauses.push(`${column} ? ${this.p(params.length)}`);
         }
         return clauses;
     }
@@ -2597,17 +2630,17 @@ export class QueryInterface {
         if (filter.has !== undefined) {
             // value = ANY(column)
             params.push(filter.has);
-            clauses.push(`$${params.length} = ANY(${column})`);
+            clauses.push(`${this.p(params.length)} = ANY(${column})`);
         }
         if (filter.hasEvery !== undefined) {
             // column @> ARRAY[...]::type[]
             params.push(filter.hasEvery);
-            clauses.push(`${column} @> $${params.length}::${elementType}[]`);
+            clauses.push(`${column} @> ${this.p(params.length)}::${elementType}[]`);
         }
         if (filter.hasSome !== undefined) {
             // column && ARRAY[...]::type[]
             params.push(filter.hasSome);
-            clauses.push(`${column} && $${params.length}::${elementType}[]`);
+            clauses.push(`${column} && ${this.p(params.length)}::${elementType}[]`);
         }
         if (filter.isEmpty === true) {
             // array_length(column, 1) IS NULL