@vibeorm/runtime 1.0.0

package/src/query-builder.ts

@@ -0,0 +1,1417 @@
+/**
+ * SQL Query Builder
+ *
+ * Takes an operation descriptor (model, operation, args) and produces
+ * parameterized SQL queries for PostgreSQL.
+ */
+
+import type {
+  ModelMeta,
+  ModelMetaMap,
+  SqlQuery,
+  Operation,
+  ScalarFieldMeta,
+} from "./types.ts";
+import { getScalarFieldMap, getModelByNameMap, PgArray } from "./types.ts";
+import { buildWhereClause } from "./where-builder.ts";
+
+// ─── SELECT Builder ───────────────────────────────────────────────
+
+export function buildSelectQuery(params: {
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  args: Record<string, unknown>;
+}): SqlQuery {
+  const { modelMeta, allModelsMeta, args } = params;
+  const table = `"${modelMeta.dbName}"`;
+  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+
+  // Determine which columns to select
+  const columns = resolveSelectColumns({ modelMeta, args });
+  const columnsSql = columns
+    .map((c) => `${table}."${c.dbName}" AS "${c.name}"`)
+    .join(", ");
+
+  // DISTINCT ON support (PostgreSQL)
+  let distinctSql = "";
+  if (args.distinct) {
+    const distinctFields = args.distinct as string[];
+    if (distinctFields.length > 0) {
+      const distinctCols = distinctFields.map((field) => {
+        const sf = sfMap.get(field);
+        return `${table}."${sf ? sf.dbName : field}"`;
+      });
+      distinctSql = `DISTINCT ON (${distinctCols.join(", ")}) `;
+    }
+  }
+
+  // Build WHERE — start with explicit where, then add cursor condition
+  let where = args.where as Record<string, unknown> | undefined;
+
+  // Cursor-based pagination: inject cursor condition into WHERE
+  // For composite cursors we need lexicographic ordering:
+  //   (a > $1) OR (a = $1 AND b > $2) OR (a = $1 AND b = $2 AND c > $3) ...
+  if (args.cursor) {
+    const cursorInput = args.cursor as Record<string, unknown>;
+    const cursorEntries = Object.entries(cursorInput).filter(
+      ([, v]) => v !== undefined
+    );
+
+    // Determine direction: positive take = forward (>), negative take = backward (<)
+    const take = args.take as number | undefined;
+    const isBackward = take !== undefined && take < 0;
+    const cmpOp = isBackward ? "lt" : "gt";
+
+    let cursorWhere: Record<string, unknown> | undefined;
+
+    if (cursorEntries.length === 1) {
+      // Single-field cursor: simple gt/lt (most common case)
+      const [field, value] = cursorEntries[0]!;
+      cursorWhere = { [field]: { [cmpOp]: value } };
+    } else if (cursorEntries.length > 1) {
+      // Composite cursor: build lexicographic OR conditions
+      // For fields [a, b, c] with forward:
+      //   (a > v1) OR (a = v1 AND b > v2) OR (a = v1 AND b = v2 AND c > v3)
+      const orBranches: Record<string, unknown>[] = [];
+      for (let i = 0; i < cursorEntries.length; i++) {
+        const branch: Record<string, unknown> = {};
+        // All preceding fields must equal their cursor values
+        for (let j = 0; j < i; j++) {
+          const [eqField, eqValue] = cursorEntries[j]!;
+          branch[eqField] = { equals: eqValue };
+        }
+        // The i-th field uses the comparison operator
+        const [cmpField, cmpValue] = cursorEntries[i]!;
+        branch[cmpField] = { [cmpOp]: cmpValue };
+        orBranches.push(branch);
+      }
+      cursorWhere = { OR: orBranches };
+    }
+
+    // Merge cursor conditions with existing where via AND
+    if (cursorWhere) {
+      where = where
+        ? { AND: [where, cursorWhere] }
+        : cursorWhere;
+    }
+  }
+
+  const whereResult = buildWhereClause({
+    where,
+    modelMeta,
+    allModelsMeta,
+    paramOffset: 0,
+  });
+
+  let paramIdx = whereResult.values.length;
+  const allValues = [...whereResult.values];
+
+  // Build ORDER BY
+  let orderBySql = "";
+  const orderByJoins: string[] = [];
+  if (args.orderBy) {
+    const orderByItems = Array.isArray(args.orderBy)
+      ? (args.orderBy as Record<string, unknown>[])
+      : [args.orderBy as Record<string, unknown>];
+
+    const orderClauses = orderByItems.flatMap((item) =>
+      Object.entries(item).map(([field, direction]) => {
+        // Null ordering: { sort: "desc", nulls: "last" }
+        if (typeof direction === "object" && direction !== null) {
+          const dirObj = direction as Record<string, unknown>;
+
+          // SortOrderWithNulls: { sort: "asc", nulls: "last" }
+          if (dirObj.sort && typeof dirObj.sort === "string") {
+            const scalarField = sfMap.get(field);
+            const col = scalarField ? scalarField.dbName : field;
+            let clause = `${table}."${col}" ${(dirObj.sort as string).toUpperCase()}`;
+            if (dirObj.nulls === "first") clause += " NULLS FIRST";
+            else if (dirObj.nulls === "last") clause += " NULLS LAST";
+            return clause;
+          }
+
+          // Relation count ordering: { posts: { _count: "desc" } }
+          if (dirObj._count && typeof dirObj._count === "string") {
+            const relField = modelMeta.relationFields.find((r) => r.name === field);
+            if (relField) {
+              const modelMap = getModelByNameMap({ allModelsMeta });
+              const relatedMeta = modelMap.get(relField.relatedModel);
+              if (relatedMeta) {
+                const reverseRel = relatedMeta.relationFields.find(
+                  (r: { relatedModel: string; isForeignKey: boolean; fields: readonly string[] }) =>
+                    r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0
+                );
+                if (reverseRel) {
+                  const relatedSfMap = getScalarFieldMap({ scalarFields: relatedMeta.scalarFields });
+                  const fkScalar = relatedSfMap.get(reverseRel.fields[0]!);
+                  const fkDbName = fkScalar?.dbName ?? reverseRel.fields[0]!;
+                  const parentPk = modelMeta.primaryKey[0]!;
+                  const parentSf = sfMap.get(parentPk);
+                  const parentPkDb = parentSf?.dbName ?? parentPk;
+                  return `(SELECT COUNT(*) FROM "${relatedMeta.dbName}" WHERE "${relatedMeta.dbName}"."${fkDbName}" = ${table}."${parentPkDb}") ${(dirObj._count as string).toUpperCase()}`;
+                }
+              }
+            }
+            return `1 ${(dirObj._count as string).toUpperCase()}`;
+          }
+
+          // Relation field ordering: { author: { name: "asc" } }
+          const relField = modelMeta.relationFields.find((r) => r.name === field);
+          if (relField && !relField.isList) {
+            const modelMap = getModelByNameMap({ allModelsMeta });
+            const relatedMeta = modelMap.get(relField.relatedModel);
+            if (relatedMeta) {
+              const relatedAlias = `"__orderby_${field}"`;
+              // Determine join condition
+              let joinCond: string;
+              if (relField.isForeignKey && relField.fields.length > 0) {
+                const fkScalar = sfMap.get(relField.fields[0]!);
+                const fkDbName = fkScalar?.dbName ?? relField.fields[0]!;
+                const relatedSfMap = getScalarFieldMap({ scalarFields: relatedMeta.scalarFields });
+                const refScalar = relatedSfMap.get(relField.references[0]!);
+                const refDbName = refScalar?.dbName ?? relField.references[0]!;
+                joinCond = `${relatedAlias}."${refDbName}" = ${table}."${fkDbName}"`;
+              } else {
+                const reverseRel = relatedMeta.relationFields.find(
+                  (r: { relatedModel: string; isForeignKey: boolean; fields: readonly string[] }) =>
+                    r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0
+                );
+                if (reverseRel) {
+                  const relatedSfMap = getScalarFieldMap({ scalarFields: relatedMeta.scalarFields });
+                  const fkScalar = relatedSfMap.get(reverseRel.fields[0]!);
+                  const fkDbName = fkScalar?.dbName ?? reverseRel.fields[0]!;
+                  const refScalar = sfMap.get(reverseRel.references[0]!);
+                  const refDbName = refScalar?.dbName ?? reverseRel.references[0]!;
+                  joinCond = `${relatedAlias}."${fkDbName}" = ${table}."${refDbName}"`;
+                } else {
+                  joinCond = "TRUE";
+                }
+              }
+              orderByJoins.push(`LEFT JOIN "${relatedMeta.dbName}" ${relatedAlias} ON ${joinCond}`);
+
+              // Get the ordering field from the relation object
+              const relatedSfMap = getScalarFieldMap({ scalarFields: relatedMeta.scalarFields });
+              return Object.entries(dirObj).map(([relField2, relDir]) => {
+                const relSf = relatedSfMap.get(relField2);
+                const relCol = relSf?.dbName ?? relField2;
+                return `${relatedAlias}."${relCol}" ${(relDir as string).toUpperCase()}`;
+              }).join(", ");
+            }
+          }
+        }
+
+        // Simple scalar ordering
+        const scalarField = sfMap.get(field);
+        const col = scalarField ? scalarField.dbName : field;
+        return `${table}."${col}" ${(direction as string).toUpperCase()}`;
+      })
+    );
+
+    if (orderClauses.length > 0) {
+      orderBySql = ` ORDER BY ${orderClauses.join(", ")}`;
+    }
+  } else if (args.distinct) {
+    // DISTINCT ON requires ORDER BY on the same columns first
+    const distinctFields = args.distinct as string[];
+    if (distinctFields.length > 0) {
+      const distinctOrderClauses = distinctFields.map((field) => {
+        const sf = sfMap.get(field);
+        return `${table}."${sf ? sf.dbName : field}" ASC`;
+      });
+      orderBySql = ` ORDER BY ${distinctOrderClauses.join(", ")}`;
+    }
+  } else if (args.cursor) {
+    // Cursor pagination without explicit orderBy: default to ordering by cursor
+    // fields to ensure deterministic results and proper index utilization.
+    const cursorInput = args.cursor as Record<string, unknown>;
+    const cursorEntries = Object.entries(cursorInput).filter(([, v]) => v !== undefined);
+    const take = args.take as number | undefined;
+    const isBackward = take !== undefined && take < 0;
+    const defaultDir = isBackward ? "DESC" : "ASC";
+    const cursorOrderClauses = cursorEntries.map(([field]) => {
+      const sf = sfMap.get(field);
+      return `${table}."${sf ? sf.dbName : field}" ${defaultDir}`;
+    });
+    if (cursorOrderClauses.length > 0) {
+      orderBySql = ` ORDER BY ${cursorOrderClauses.join(", ")}`;
+    }
+  }
+
+  // Build LIMIT / OFFSET
+  let limitSql = "";
+  if (args.take !== undefined) {
+    paramIdx++;
+    // take can be negative for backward cursor pagination; use absolute value
+    const takeValue = Math.abs(args.take as number);
+    limitSql = ` LIMIT $${paramIdx}`;
+    allValues.push(takeValue);
+  }
+
+  let offsetSql = "";
+  if (args.skip !== undefined) {
+    paramIdx++;
+    offsetSql = ` OFFSET $${paramIdx}`;
+    allValues.push(args.skip);
+  }
+
+  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
+  const joinsPart = orderByJoins.length > 0 ? ` ${orderByJoins.join(" ")}` : "";
+  const text = `SELECT ${distinctSql}${columnsSql} FROM ${table}${joinsPart}${wherePart}${orderBySql}${limitSql}${offsetSql}`;
+
+  return { text, values: allValues };
+}
+
+// ─── INSERT Builder ───────────────────────────────────────────────
+
+export function buildInsertQuery(params: {
+  modelMeta: ModelMeta;
+  data: Record<string, unknown>;
+}): SqlQuery {
+  const { modelMeta, data } = params;
+  const table = `"${modelMeta.dbName}"`;
+  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+
+  // Filter to only scalar fields that are present in data
+  const entries: Array<{ dbName: string; value: unknown }> = [];
+
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined) continue;
+    const scalarField = sfMap.get(key);
+    if (scalarField) {
+      entries.push({ dbName: scalarField.dbName, value });
+    }
+  }
+
+  if (entries.length === 0) {
+    // Insert with default values only
+    const returningCols = modelMeta.scalarFields
+      .map((f) => `"${f.dbName}" AS "${f.name}"`)
+      .join(", ");
+    return {
+      text: `INSERT INTO ${table} DEFAULT VALUES RETURNING ${returningCols}`,
+      values: [],
+    };
+  }
+
+  const columns = entries.map((e) => `"${e.dbName}"`).join(", ");
+  const placeholders = entries.map((_, i) => `$${i + 1}`).join(", ");
+  const values = entries.map((e) => e.value);
+
+  const returningCols = modelMeta.scalarFields
+    .map((f) => `"${f.dbName}" AS "${f.name}"`)
+    .join(", ");
+
+  const text = `INSERT INTO ${table} (${columns}) VALUES (${placeholders}) RETURNING ${returningCols}`;
+
+  return { text, values };
+}
+
+// ─── UPDATE Builder ───────────────────────────────────────────────
+
+export function buildUpdateQuery(params: {
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  where: Record<string, unknown>;
+  data: Record<string, unknown>;
+}): SqlQuery {
+  const { modelMeta, allModelsMeta, where, data } = params;
+  const table = `"${modelMeta.dbName}"`;
+  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+
+  let paramIdx = 0;
+  const allValues: unknown[] = [];
+  const setClauses: string[] = [];
+
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined) continue;
+    const scalarField = sfMap.get(key);
+    if (!scalarField) continue;
+
+    const setResult = buildSetClause({
+      dbName: scalarField.dbName,
+      value,
+      paramIdx,
+    });
+    setClauses.push(setResult.sql);
+    allValues.push(...setResult.values);
+    paramIdx += setResult.values.length;
+  }
+
+  // Build WHERE
+  const whereResult = buildWhereClause({
+    where,
+    modelMeta,
+    allModelsMeta,
+    paramOffset: paramIdx,
+  });
+  allValues.push(...whereResult.values);
+
+  const returningCols = modelMeta.scalarFields
+    .map((f) => `"${f.dbName}" AS "${f.name}"`)
+    .join(", ");
+
+  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
+  const text = `UPDATE ${table} SET ${setClauses.join(", ")}${wherePart} RETURNING ${returningCols}`;
+
+  return { text, values: allValues };
+}
+
+// ─── DELETE Builder ───────────────────────────────────────────────
+
+export function buildDeleteQuery(params: {
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  where: Record<string, unknown>;
+}): SqlQuery {
+  const { modelMeta, allModelsMeta, where } = params;
+  const table = `"${modelMeta.dbName}"`;
+
+  const whereResult = buildWhereClause({
+    where,
+    modelMeta,
+    allModelsMeta,
+    paramOffset: 0,
+  });
+
+  const returningCols = modelMeta.scalarFields
+    .map((f) => `"${f.dbName}" AS "${f.name}"`)
+    .join(", ");
+
+  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
+  const text = `DELETE FROM ${table}${wherePart} RETURNING ${returningCols}`;
+
+  return { text, values: whereResult.values };
+}
+
+// ─── COUNT Builder ────────────────────────────────────────────────
+
+export function buildCountQuery(params: {
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  args: Record<string, unknown>;
+  countStrategy?: "direct" | "subquery";
+}): SqlQuery {
+  const { modelMeta, allModelsMeta, args, countStrategy = "direct" } = params;
+  const table = `"${modelMeta.dbName}"`;
+
+  const whereResult = buildWhereClause({
+    where: args.where as Record<string, unknown> | undefined,
+    modelMeta,
+    allModelsMeta,
+    paramOffset: 0,
+  });
+
+  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
+
+  if (countStrategy === "subquery") {
+    // Wrap in a subquery with OFFSET 0. This can produce better query plans
+    // on serverless/proxy PostgreSQL providers where the standard COUNT(*)
+    // path chooses a suboptimal plan. The OFFSET 0 is a no-op but prevents
+    // PostgreSQL from flattening the subquery, which can change plan choice.
+    const pkCol = `${table}."${modelMeta.primaryKey[0]}"`;
+    const offsetIdx = whereResult.values.length + 1;
+    const text = `SELECT COUNT(*) AS "count" FROM (SELECT ${pkCol} FROM ${table}${wherePart} OFFSET $${offsetIdx}) AS "sub"`;
+    return { text, values: [...whereResult.values, 0] };
+  }
+
+  const text = `SELECT COUNT(*) AS "count" FROM ${table}${wherePart}`;
+  return { text, values: whereResult.values };
+}
+
+// ─── Relation Query Builder ───────────────────────────────────────
+
+/**
+ * Build a query to load related records for a batch of parent IDs.
+ * Used for to-many relations (hybrid strategy: separate batched query).
+ */
+export type RelationSqlQuery = SqlQuery & {
+  /** When the FK column is already in the selected columns, this holds
+   *  its application-level field name so callers can use it for stitching
+   *  instead of the __vibeorm_fk alias. undefined means __vibeorm_fk is present. */
+  fkFieldName?: string;
+};
+
+export function buildRelationQuery(params: {
+  parentModelMeta: ModelMeta;
+  relationMeta: {
+    readonly relatedModel: string;
+    readonly type: string;
+    readonly fields: readonly string[];
+    readonly references: readonly string[];
+    readonly isList: boolean;
+  };
+  relatedModelMeta: ModelMeta;
+  parentIds: unknown[];
+  args?: Record<string, unknown>;
+  allModelsMeta: ModelMetaMap;
+}): RelationSqlQuery {
+  const {
+    parentModelMeta,
+    relationMeta,
+    relatedModelMeta,
+    parentIds,
+    args = {},
+    allModelsMeta,
+  } = params;
+
+  const table = `"${relatedModelMeta.dbName}"`;
+  const sfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
+
+  // Determine which columns to select
+  const columns = resolveSelectColumns({
+    modelMeta: relatedModelMeta,
+    args,
+  });
+  const columnsSql = columns
+    .map((c) => `${table}."${c.dbName}" AS "${c.name}"`)
+    .join(", ");
+
+  const allValues: unknown[] = [];
+  let paramIdx = 0;
+
+  // The FK column on the related model that references the parent
+  let fkDbName: string;
+  let fkFieldName: string | undefined;
+
+  // Access relationName for disambiguation (multi-FK scenarios like Follow)
+  const parentRelationName = (relationMeta as { relationName?: string }).relationName;
+
+  if (relationMeta.fields.length > 0) {
+    const reverseRelation = relatedModelMeta.relationFields.find(
+      (r) =>
+        r.relatedModel === parentModelMeta.name &&
+        r.isForeignKey &&
+        r.references.length > 0 &&
+        (!parentRelationName || r.relationName === parentRelationName)
+    );
+    if (reverseRelation) {
+      fkFieldName = reverseRelation.fields[0]!;
+      const fkField = sfMap.get(fkFieldName);
+      fkDbName = fkField?.dbName ?? fkFieldName;
+    } else {
+      fkDbName = relationMeta.fields[0]!;
+    }
+  } else {
+    const reverseRelation = relatedModelMeta.relationFields.find(
+      (r) =>
+        r.relatedModel === parentModelMeta.name &&
+        r.isForeignKey &&
+        (!parentRelationName || r.relationName === parentRelationName)
+    );
+    if (reverseRelation) {
+      fkFieldName = reverseRelation.fields[0]!;
+      const fkField = sfMap.get(fkFieldName);
+      fkDbName = fkField?.dbName ?? fkFieldName;
+    } else {
+      fkDbName = `${parentModelMeta.name.toLowerCase()}Id`;
+    }
+  }
+
+  // Only add __vibeorm_fk alias if the FK column isn't already in the selected columns.
+  // This avoids transferring the same column value twice per row.
+  const fkAlreadySelected = columns.some((c) => c.dbName === fkDbName);
+  const fkSelectSql = fkAlreadySelected
+    ? ""
+    : `, ${table}."${fkDbName}" AS "__vibeorm_fk"`;
+
+  paramIdx++;
+  allValues.push(new PgArray(parentIds));
+
+  let whereSql = `${table}."${fkDbName}" = ANY($${paramIdx})`;
+
+  // Add any additional where from nested args
+  if (args.where) {
+    const subWhere = buildWhereClause({
+      where: args.where as Record<string, unknown>,
+      modelMeta: relatedModelMeta,
+      allModelsMeta,
+      paramOffset: paramIdx,
+    });
+    if (subWhere.sql) {
+      whereSql += ` AND (${subWhere.sql})`;
+      allValues.push(...subWhere.values);
+      paramIdx += subWhere.values.length;
+    }
+  }
+
+  // ORDER BY
+  let orderBySql = "";
+  if (args.orderBy) {
+    const orderByItems = Array.isArray(args.orderBy)
+      ? (args.orderBy as Record<string, string>[])
+      : [args.orderBy as Record<string, string>];
+
+    const orderClauses = orderByItems.flatMap((item) =>
+      Object.entries(item).map(([field, direction]) => {
+        const scalarField = sfMap.get(field);
+        const col = scalarField ? scalarField.dbName : field;
+        return `${table}."${col}" ${direction.toUpperCase()}`;
+      })
+    );
+
+    if (orderClauses.length > 0) {
+      orderBySql = ` ORDER BY ${orderClauses.join(", ")}`;
+    }
+  }
+
+  // Per-parent LIMIT/OFFSET using ROW_NUMBER() window function
+  if (args.take !== undefined || args.skip !== undefined) {
+    let windowOrderBy = "";
+    if (args.orderBy) {
+      const orderByItems = Array.isArray(args.orderBy)
+        ? (args.orderBy as Record<string, string>[])
+        : [args.orderBy as Record<string, string>];
+      const clauses = orderByItems.flatMap((item) =>
+        Object.entries(item).map(([field, direction]) => {
+          const sf = sfMap.get(field);
+          const col = sf ? sf.dbName : field;
+          return `${table}."${col}" ${(direction as string).toUpperCase()}`;
+        })
+      );
+      if (clauses.length > 0) windowOrderBy = clauses.join(", ");
+    }
+    if (!windowOrderBy) {
+      const pk = relatedModelMeta.primaryKey[0];
+      if (pk) {
+        const pkScalar = sfMap.get(pk);
+        windowOrderBy = `${table}."${pkScalar?.dbName ?? pk}" ASC`;
+      } else {
+        windowOrderBy = "1";
+      }
+    }
+
+    const fkSelectInner = fkAlreadySelected
+      ? ""
+      : `, ${table}."${fkDbName}" AS "__vibeorm_fk"`;
+    // ORDER BY is already captured in the ROW_NUMBER() OVER clause; omit the
+    // redundant trailing ORDER BY to avoid an extra sort node in the plan.
+    const innerSql = `SELECT ${columnsSql}${fkSelectInner}, ROW_NUMBER() OVER (PARTITION BY ${table}."${fkDbName}" ORDER BY ${windowOrderBy}) AS "__vibeorm_rn" FROM ${table} WHERE ${whereSql}`;
+
+    // Build compound WHERE condition on __vibeorm_rn
+    const rnConditions: string[] = [];
+    if (args.skip !== undefined) {
+      paramIdx++;
+      allValues.push(args.skip);
+      rnConditions.push(`__ranked."__vibeorm_rn" > $${paramIdx}`);
+    }
+    if (args.take !== undefined) {
+      paramIdx++;
+      if (args.skip !== undefined) {
+        // upper bound = skip + take
+        allValues.push((args.skip as number) + (args.take as number));
+      } else {
+        allValues.push(args.take);
+      }
+      rnConditions.push(`__ranked."__vibeorm_rn" <= $${paramIdx}`);
+    }
+
+    const text = `SELECT * FROM (${innerSql}) __ranked WHERE ${rnConditions.join(" AND ")}`;
+
+    return { text, values: allValues, fkFieldName: fkAlreadySelected ? fkFieldName : undefined };
+  }
+
+  const text = `SELECT ${columnsSql}${fkSelectSql} FROM ${table} WHERE ${whereSql}${orderBySql}`;
+
+  return { text, values: allValues, fkFieldName: fkAlreadySelected ? fkFieldName : undefined };
+}
+
+// ─── Many-to-Many Relation Query Builder ──────────────────────────
+
+/**
+ * Build a query to load M:N related records via an implicit join table.
+ * E.g., Post.tags via "_PostToTag" join table.
+ */
+export function buildManyToManyQuery(params: {
+  parentModelMeta: ModelMeta;
+  relationMeta: {
+    readonly relatedModel: string;
+    readonly type: string;
+    readonly isList: boolean;
+    readonly joinTable?: string;
+    readonly relationName?: string;
+  };
+  relatedModelMeta: ModelMeta;
+  parentIds: unknown[];
+  args?: Record<string, unknown>;
+  allModelsMeta: ModelMetaMap;
+}): RelationSqlQuery {
+  const {
+    parentModelMeta,
+    relationMeta,
+    relatedModelMeta,
+    parentIds,
+    args = {},
+    allModelsMeta,
+  } = params;
+
+  const joinTable = `"${(relationMeta as { joinTable?: string }).joinTable}"`;
+  const relatedTable = `"${relatedModelMeta.dbName}"`;
+  const sfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
+
+  // Determine A vs B: alphabetical model name order
+  const sorted = [parentModelMeta.name, relatedModelMeta.name].sort();
+  const parentIsA = parentModelMeta.name === sorted[0];
+  const parentCol = parentIsA ? "A" : "B";
+  const relatedCol = parentIsA ? "B" : "A";
+
+  // Determine which columns to select from the related model
+  const columns = resolveSelectColumns({
+    modelMeta: relatedModelMeta,
+    args,
+  });
+  const columnsSql = columns
+    .map((c) => `${relatedTable}."${c.dbName}" AS "${c.name}"`)
+    .join(", ");
+
+  const allValues: unknown[] = [];
+  let paramIdx = 0;
+
+  // Build = ANY clause for parent IDs (stable SQL shape for prepared statement caching)
+  paramIdx++;
+  allValues.push(new PgArray(parentIds));
+
+  // Related model PK (typically "id")
+  const relatedPk = relatedModelMeta.primaryKey[0];
+  const relatedPkSf = relatedPk ? sfMap.get(relatedPk) : undefined;
+  const relatedPkDb = relatedPkSf?.dbName ?? relatedPk ?? "id";
+
+  let whereSql = `${joinTable}."${parentCol}" = ANY($${paramIdx})`;
+
+  // Add any additional where from nested args
+  if (args.where) {
+    const subWhere = buildWhereClause({
+      where: args.where as Record<string, unknown>,
+      modelMeta: relatedModelMeta,
+      allModelsMeta,
+      paramOffset: paramIdx,
+    });
+    if (subWhere.sql) {
+      whereSql += ` AND (${subWhere.sql})`;
+      allValues.push(...subWhere.values);
+      paramIdx += subWhere.values.length;
+    }
+  }
+
+  // ORDER BY
+  let orderBySql = "";
+  if (args.orderBy) {
+    const orderByItems = Array.isArray(args.orderBy)
+      ? (args.orderBy as Record<string, string>[])
+      : [args.orderBy as Record<string, string>];
+
+    const orderClauses = orderByItems.flatMap((item) =>
+      Object.entries(item).map(([field, direction]) => {
+        const scalarField = sfMap.get(field);
+        const col = scalarField ? scalarField.dbName : field;
+        return `${relatedTable}."${col}" ${direction.toUpperCase()}`;
+      })
+    );
+
+    if (orderClauses.length > 0) {
+      orderBySql = ` ORDER BY ${orderClauses.join(", ")}`;
+    }
+  }
+
+  // LIMIT / take + skip support via ROW_NUMBER
+  if (args.take !== undefined || args.skip !== undefined) {
+    let windowOrderBy = "";
+    if (args.orderBy) {
+      const orderByItems = Array.isArray(args.orderBy)
+        ? (args.orderBy as Record<string, string>[])
+        : [args.orderBy as Record<string, string>];
+      const clauses = orderByItems.flatMap((item) =>
+        Object.entries(item).map(([field, direction]) => {
+          const sf = sfMap.get(field);
+          const col = sf ? sf.dbName : field;
+          return `${relatedTable}."${col}" ${(direction as string).toUpperCase()}`;
+        })
+      );
+      if (clauses.length > 0) windowOrderBy = clauses.join(", ");
+    }
+    if (!windowOrderBy) {
+      windowOrderBy = `${relatedTable}."${relatedPkDb}" ASC`;
+    }
+
+    // ORDER BY is already captured in the ROW_NUMBER() OVER clause; omit the
+    // redundant trailing ORDER BY to avoid an extra sort node in the plan.
+    const innerSql = `SELECT ${columnsSql}, ${joinTable}."${parentCol}" AS "__vibeorm_fk", ROW_NUMBER() OVER (PARTITION BY ${joinTable}."${parentCol}" ORDER BY ${windowOrderBy}) AS "__vibeorm_rn" FROM ${relatedTable} INNER JOIN ${joinTable} ON ${joinTable}."${relatedCol}" = ${relatedTable}."${relatedPkDb}" WHERE ${whereSql}`;
+
+    const rnConditions: string[] = [];
+    if (args.skip !== undefined) {
+      paramIdx++;
+      allValues.push(args.skip);
+      rnConditions.push(`__ranked."__vibeorm_rn" > $${paramIdx}`);
+    }
+    if (args.take !== undefined) {
+      paramIdx++;
+      if (args.skip !== undefined) {
+        allValues.push((args.skip as number) + (args.take as number));
+      } else {
+        allValues.push(args.take);
+      }
+      rnConditions.push(`__ranked."__vibeorm_rn" <= $${paramIdx}`);
+    }
+
+    const text = `SELECT * FROM (${innerSql}) __ranked WHERE ${rnConditions.join(" AND ")}`;
+    return { text, values: allValues };
+  }
+
+  const text = `SELECT ${columnsSql}, ${joinTable}."${parentCol}" AS "__vibeorm_fk" FROM ${relatedTable} INNER JOIN ${joinTable} ON ${joinTable}."${relatedCol}" = ${relatedTable}."${relatedPkDb}" WHERE ${whereSql}${orderBySql}`;
+
+  return { text, values: allValues };
+}
+
+// ─── INSERT MANY Builder ──────────────────────────────────────────
+
+/**
+ * Build a multi-row INSERT query.
+ * Produces: INSERT INTO "Table" ("col1", "col2") VALUES ($1, $2), ($3, $4), ...
+ *
+ * Handles varying keys across records by computing the union of all keys
+ * and using DEFAULT for missing ones.
+ */
+export function buildInsertManyQuery(params: {
+  modelMeta: ModelMeta;
+  data: Record<string, unknown>[];
+  skipDuplicates?: boolean;
+  returning?: boolean;
+  selectFields?: string[];
+}): SqlQuery {
+  const { modelMeta, data, skipDuplicates = false, returning = false, selectFields } = params;
+  const table = `"${modelMeta.dbName}"`;
+  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+
+  if (data.length === 0) {
+    // Empty data — return a no-op that returns count 0
+    return { text: `SELECT 0 AS "count"`, values: [] };
+  }
+
+  // Compute the union of all keys across all records, filtered to scalar fields
+  const allKeys = new Set<string>();
+  for (const record of data) {
+    for (const key of Object.keys(record)) {
+      if (record[key] === undefined) continue;
+      if (sfMap.has(key)) {
+        allKeys.add(key);
+      }
+    }
+  }
+
+  const orderedKeys = [...allKeys];
+
+  if (orderedKeys.length === 0) {
+    // All records have empty data — insert defaults for each row
+    // PostgreSQL doesn't support multi-row DEFAULT VALUES, so use a union
+    const unionParts = data.map(() => `SELECT`);
+    // Actually just use single inserts... or use a CTE
+    // Simpler: use VALUES with explicit DEFAULT keywords
+    // PostgreSQL supports: INSERT INTO t DEFAULT VALUES (but only one row)
+    // For multiple: INSERT INTO t (col) VALUES (DEFAULT), (DEFAULT), ...
+    // We need at least one column. Use the PK column.
+    const pkField = modelMeta.scalarFields[0]!;
+    const col = `"${pkField.dbName}"`;
+    const valueRows = data.map(() => `(DEFAULT)`).join(", ");
+    const returningClause = returning
+      ? ` RETURNING ${resolveReturningColumns({ modelMeta, selectFields })}`
+      : "";
+    const conflictClause = skipDuplicates ? ` ON CONFLICT DO NOTHING` : "";
+    return {
+      text: `INSERT INTO ${table} (${col}) VALUES ${valueRows}${conflictClause}${returningClause}`,
+      values: [],
+    };
+  }
+
+  // Map keys to DB column names
+  const columnMap = orderedKeys.map((key) => {
+    const scalarField = sfMap.get(key)!;
+    return { key, dbName: scalarField.dbName };
+  });
+
+  const columns = columnMap.map((c) => `"${c.dbName}"`).join(", ");
+
+  // Build VALUES rows
+  const allValues: unknown[] = [];
+  let paramIdx = 0;
+  const valueRows: string[] = [];
+
+  for (const record of data) {
+    const placeholders: string[] = [];
+    for (const { key } of columnMap) {
+      const value = record[key];
+      if (value === undefined) {
+        placeholders.push("DEFAULT");
+      } else {
+        paramIdx++;
+        placeholders.push(`$${paramIdx}`);
+        allValues.push(value);
+      }
+    }
+    valueRows.push(`(${placeholders.join(", ")})`);
+  }
+
+  const conflictClause = skipDuplicates ? ` ON CONFLICT DO NOTHING` : "";
+  const returningClause = returning
+    ? ` RETURNING ${resolveReturningColumns({ modelMeta, selectFields })}`
+    : "";
+
+  const text = `INSERT INTO ${table} (${columns}) VALUES ${valueRows.join(", ")}${conflictClause}${returningClause}`;
+
+  return { text, values: allValues };
+}
+
+/**
+ * Resolve RETURNING columns for insert many queries.
+ */
+function resolveReturningColumns(params: {
+  modelMeta: ModelMeta;
+  selectFields?: string[];
+}): string {
+  const { modelMeta, selectFields } = params;
+
+  if (selectFields && selectFields.length > 0) {
+    const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+    return selectFields
+      .map((name) => {
+        const sf = sfMap.get(name);
+        if (sf) return `"${sf.dbName}" AS "${sf.name}"`;
+        return `"${name}" AS "${name}"`;
+      })
+      .join(", ");
+  }
+
+  return modelMeta.scalarFields
+    .map((f) => `"${f.dbName}" AS "${f.name}"`)
+    .join(", ");
+}
+
+// ─── UPDATE MANY Builder ──────────────────────────────────────────
+
+/**
+ * Build an UPDATE query without RETURNING (for updateMany).
+ * Uses a subquery COUNT trick to return the affected row count.
+ */
+export function buildUpdateManyQuery(params: {
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  where: Record<string, unknown>;
+  data: Record<string, unknown>;
+}): SqlQuery {
+  const { modelMeta, allModelsMeta, where, data } = params;
+  const table = `"${modelMeta.dbName}"`;
+  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+
+  let paramIdx = 0;
+  const allValues: unknown[] = [];
+  const setClauses: string[] = [];
+
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined) continue;
+    const scalarField = sfMap.get(key);
+    if (!scalarField) continue;
+
+    const setResult = buildSetClause({
+      dbName: scalarField.dbName,
+      value,
+      paramIdx,
+    });
+    setClauses.push(setResult.sql);
+    allValues.push(...setResult.values);
+    paramIdx += setResult.values.length;
+  }
+
+  if (setClauses.length === 0) {
+    return { text: `SELECT 0 AS "count"`, values: [] };
+  }
+
+  // Build WHERE
+  const whereResult = buildWhereClause({
+    where,
+    modelMeta,
+    allModelsMeta,
+    paramOffset: paramIdx,
+  });
+  allValues.push(...whereResult.values);
+
+  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
+  const text = `UPDATE ${table} SET ${setClauses.join(", ")}${wherePart}`;
+
+  return { text, values: allValues };
+}
+
+// ─── AGGREGATE Builder ────────────────────────────────────────────
+
+/**
+ * Build an aggregate query with _count, _avg, _sum, _min, _max.
+ */
+export function buildAggregateQuery(params: {
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  args: Record<string, unknown>;
+}): SqlQuery {
+  const { modelMeta, allModelsMeta, args } = params;
+  const table = `"${modelMeta.dbName}"`;
+  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+
+  const selectParts: string[] = [];
+
+  // _count
+  const countArg = args._count;
+  if (countArg === true) {
+    selectParts.push(`COUNT(*) AS "_count__all"`);
+  } else if (typeof countArg === "object" && countArg !== null) {
+    const countFields = countArg as Record<string, boolean>;
+    if (countFields._all) {
+      selectParts.push(`COUNT(*) AS "_count__all"`);
+    }
+    for (const [field, enabled] of Object.entries(countFields)) {
+      if (field === "_all" || !enabled) continue;
+      const sf = sfMap.get(field);
+      const col = sf ? sf.dbName : field;
+      selectParts.push(`COUNT("${col}") AS "_count__${field}"`);
+    }
+  }
+
+  // _avg, _sum, _min, _max
+  for (const aggFn of ["_avg", "_sum", "_min", "_max"] as const) {
+    const aggArg = args[aggFn];
+    if (typeof aggArg === "object" && aggArg !== null) {
+      const sqlFn = aggFn.slice(1).toUpperCase(); // "avg" → "AVG"
+      const fields = aggArg as Record<string, boolean>;
+      for (const [field, enabled] of Object.entries(fields)) {
+        if (!enabled) continue;
+        const sf = sfMap.get(field);
+        const col = sf ? sf.dbName : field;
+        selectParts.push(`${sqlFn}("${col}") AS "${aggFn}__${field}"`);
+      }
+    }
+  }
+
+  if (selectParts.length === 0) {
+    // No aggregation requested — just count all
+    selectParts.push(`COUNT(*) AS "_count__all"`);
+  }
+
+  // Build WHERE
+  const whereResult = buildWhereClause({
+    where: args.where as Record<string, unknown> | undefined,
+    modelMeta,
+    allModelsMeta,
+    paramOffset: 0,
+  });
+
+  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
+  const text = `SELECT ${selectParts.join(", ")} FROM ${table}${wherePart}`;
+
+  return { text, values: whereResult.values };
+}
+
+// ─── GROUP BY Builder ─────────────────────────────────────────────
+
+/**
+ * Build a GROUP BY query with aggregate functions and HAVING clause.
+ */
+export function buildGroupByQuery(params: {
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  args: Record<string, unknown>;
+}): SqlQuery {
+  const { modelMeta, allModelsMeta, args } = params;
+  const table = `"${modelMeta.dbName}"`;
+  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+
+  const by = args.by as string[];
+  if (!by || by.length === 0) {
+    throw new Error("groupBy requires a non-empty 'by' array");
+  }
+
+  // Group-by columns
+  const groupColumns = by.map((field) => {
+    const sf = sfMap.get(field);
+    const col = sf ? sf.dbName : field;
+    return { field, col, dbName: col };
+  });
+
+  const selectParts: string[] = groupColumns.map(
+    (g) => `${table}."${g.col}" AS "${g.field}"`
+  );
+
+  // Aggregate functions
+  const countArg = args._count;
+  if (countArg === true) {
+    selectParts.push(`COUNT(*) AS "_count__all"`);
+  } else if (typeof countArg === "object" && countArg !== null) {
+    const countFields = countArg as Record<string, boolean>;
+    if (countFields._all) {
+      selectParts.push(`COUNT(*) AS "_count__all"`);
+    }
+    for (const [field, enabled] of Object.entries(countFields)) {
+      if (field === "_all" || !enabled) continue;
+      const sf = sfMap.get(field);
+      const col = sf ? sf.dbName : field;
+      selectParts.push(`COUNT("${col}") AS "_count__${field}"`);
+    }
+  }
+
+  for (const aggFn of ["_avg", "_sum", "_min", "_max"] as const) {
+    const aggArg = args[aggFn];
+    if (typeof aggArg === "object" && aggArg !== null) {
+      const sqlFn = aggFn.slice(1).toUpperCase();
+      const fields = aggArg as Record<string, boolean>;
+      for (const [field, enabled] of Object.entries(fields)) {
+        if (!enabled) continue;
+        const sf = sfMap.get(field);
+        const col = sf ? sf.dbName : field;
+        selectParts.push(`${sqlFn}("${col}") AS "${aggFn}__${field}"`);
+      }
+    }
+  }
+
+  // Build WHERE
+  const whereResult = buildWhereClause({
+    where: args.where as Record<string, unknown> | undefined,
+    modelMeta,
+    allModelsMeta,
+    paramOffset: 0,
+  });
+  let paramIdx = whereResult.values.length;
+  const allValues = [...whereResult.values];
+
+  const wherePart = whereResult.sql ? ` WHERE ${whereResult.sql}` : "";
+
+  // GROUP BY
+  const groupBySql = groupColumns
+    .map((g) => `${table}."${g.col}"`)
+    .join(", ");
+
+  // HAVING
+  let havingSql = "";
+  if (args.having) {
+    const havingResult = buildHavingClause({
+      having: args.having as Record<string, unknown>,
+      modelMeta,
+      paramOffset: paramIdx,
+    });
+    if (havingResult.sql) {
+      havingSql = ` HAVING ${havingResult.sql}`;
+      allValues.push(...havingResult.values);
+      paramIdx += havingResult.values.length;
+    }
+  }
+
+  // ORDER BY
+  let orderBySql = "";
+  if (args.orderBy) {
+    const orderByItems = Array.isArray(args.orderBy)
+      ? (args.orderBy as Record<string, string>[])
+      : [args.orderBy as Record<string, string>];
+
+    const orderClauses = orderByItems.flatMap((item) =>
+      Object.entries(item).map(([field, direction]) => {
+        // Support ordering by aggregate: { _count: { id: "asc" } }
+         if (field.startsWith("_") && typeof direction === "object" && direction !== null) {
+          const aggEntries = Object.entries(direction as Record<string, string>);
+          return aggEntries.map(([aggField, aggDir]) => {
+            const sqlFn = field.slice(1).toUpperCase();
+            if (field === "_count" && aggField === "_all") {
+              return `COUNT(*) ${(aggDir as string).toUpperCase()}`;
+            }
+            const sf = sfMap.get(aggField);
+            const col = sf ? sf.dbName : aggField;
+            return `${sqlFn}("${col}") ${(aggDir as string).toUpperCase()}`;
+          }).join(", ");
+        }
+        const sf = sfMap.get(field);
+        const col = sf ? sf.dbName : field;
+        return `${table}."${col}" ${(direction as string).toUpperCase()}`;
+      })
+    );
+
+    if (orderClauses.length > 0) {
+      orderBySql = ` ORDER BY ${orderClauses.join(", ")}`;
+    }
+  }
+
+  // LIMIT / OFFSET
+  let limitSql = "";
+  if (args.take !== undefined) {
+    paramIdx++;
+    limitSql = ` LIMIT $${paramIdx}`;
+    allValues.push(args.take);
+  }
+
+  let offsetSql = "";
+  if (args.skip !== undefined) {
+    paramIdx++;
+    offsetSql = ` OFFSET $${paramIdx}`;
+    allValues.push(args.skip);
+  }
+
+  const text = `SELECT ${selectParts.join(", ")} FROM ${table}${wherePart} GROUP BY ${groupBySql}${havingSql}${orderBySql}${limitSql}${offsetSql}`;
+
+  return { text, values: allValues };
+}
+
+// ─── HAVING Clause Builder ────────────────────────────────────────
+
+/**
+ * Build a HAVING clause from Prisma-style having input.
+ * Supports: { field: { _avg: { gt: 10 }, _count: { gte: 5 } } }
+ */
+function buildHavingClause(params: {
+  having: Record<string, unknown>;
+  modelMeta: ModelMeta;
+  paramOffset: number;
+}): { sql: string; values: unknown[] } {
+  const { having, modelMeta, paramOffset } = params;
+  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+  const conditions: string[] = [];
+  const values: unknown[] = [];
+  let paramIdx = paramOffset;
+
+  for (const [field, filter] of Object.entries(having)) {
+    if (filter === undefined) continue;
+    if (typeof filter !== "object" || filter === null) continue;
+
+    const filterObj = filter as Record<string, unknown>;
+
+    for (const [aggFn, comparison] of Object.entries(filterObj)) {
+      if (!aggFn.startsWith("_") || typeof comparison !== "object" || comparison === null) continue;
+
+      const sqlFn = aggFn.slice(1).toUpperCase(); // "_avg" → "AVG"
+      const sf = sfMap.get(field);
+      const col = sf ? sf.dbName : field;
+
+      const compObj = comparison as Record<string, unknown>;
+      for (const [op, val] of Object.entries(compObj)) {
+        if (val === undefined) continue;
+        paramIdx++;
+        values.push(val);
+
+        let sqlOp: string;
+        switch (op) {
+          case "equals": sqlOp = "="; break;
+          case "not": sqlOp = "!="; break;
+          case "lt": sqlOp = "<"; break;
+          case "lte": sqlOp = "<="; break;
+          case "gt": sqlOp = ">"; break;
+          case "gte": sqlOp = ">="; break;
+          default: continue;
+        }
+
+        conditions.push(`${sqlFn}("${col}") ${sqlOp} $${paramIdx}`);
+      }
+    }
+  }
+
+  return {
+    sql: conditions.join(" AND "),
+    values,
+  };
+}
+
+// ─── SET Clause Builder (atomic ops + list ops) ──────────────────
+
+/**
+ * Build a single SET clause for an UPDATE statement.
+ * Handles:
+ * - Plain values: "col" = $N
+ * - Atomic number ops: { increment: N } → "col" = "col" + $N
+ * - Scalar list ops: { set: [...] } → "col" = $N, { push: v } → "col" = array_append("col", $N)
+ */
+function buildSetClause(params: {
+  dbName: string;
+  value: unknown;
+  paramIdx: number;
+}): { sql: string; values: unknown[] } {
+  const { dbName, value, paramIdx } = params;
+  let idx = paramIdx;
+
+  // Check for atomic number operations: { increment, decrement, multiply, divide, set }
+  if (typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date)) {
+    const ops = value as Record<string, unknown>;
+
+    if (ops.increment !== undefined) {
+      idx++;
+      return { sql: `"${dbName}" = "${dbName}" + $${idx}`, values: [ops.increment] };
+    }
+    if (ops.decrement !== undefined) {
+      idx++;
+      return { sql: `"${dbName}" = "${dbName}" - $${idx}`, values: [ops.decrement] };
+    }
+    if (ops.multiply !== undefined) {
+      idx++;
+      return { sql: `"${dbName}" = "${dbName}" * $${idx}`, values: [ops.multiply] };
+    }
+    if (ops.divide !== undefined) {
+      idx++;
+      return { sql: `"${dbName}" = "${dbName}" / $${idx}`, values: [ops.divide] };
+    }
+
+    // Scalar list operations: { set: [...] } or { push: value }
+    if ("push" in ops) {
+      const pushVal = ops.push;
+      if (Array.isArray(pushVal)) {
+        // Push multiple: "col" = "col" || $N
+        idx++;
+        return { sql: `"${dbName}" = "${dbName}" || $${idx}`, values: [pushVal] };
+      } else {
+        // Push single: "col" = array_append("col", $N)
+        idx++;
+        return { sql: `"${dbName}" = array_append("${dbName}", $${idx})`, values: [pushVal] };
+      }
+    }
+
+    if ("set" in ops) {
+      idx++;
+      return { sql: `"${dbName}" = $${idx}`, values: [ops.set] };
+    }
+  }
+
+  // Plain value
+  idx++;
+  return { sql: `"${dbName}" = $${idx}`, values: [value] };
+}
+
+// ─── UPSERT Builder (INSERT ... ON CONFLICT) ─────────────────────
+
+/**
+ * Build an atomic upsert query using INSERT ... ON CONFLICT DO UPDATE SET.
+ * This is race-condition-free unlike the findUnique + create/update approach.
+ */
+export function buildUpsertQuery(params: {
+  modelMeta: ModelMeta;
+  where: Record<string, unknown>;
+  create: Record<string, unknown>;
+  update: Record<string, unknown>;
+}): SqlQuery {
+  const { modelMeta, where, create, update } = params;
+  const table = `"${modelMeta.dbName}"`;
+  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+
+  // Determine conflict columns from where clause (unique fields)
+  const conflictCols: string[] = [];
+  for (const key of Object.keys(where)) {
+    const sf = sfMap.get(key);
+    if (sf) {
+      conflictCols.push(`"${sf.dbName}"`);
+    }
+  }
+
+  // If no conflict columns, fallback to primary key
+  if (conflictCols.length === 0) {
+    for (const pk of modelMeta.primaryKey) {
+      const sf = sfMap.get(pk);
+      conflictCols.push(`"${sf?.dbName ?? pk}"`);
+    }
+  }
+
+  // Build INSERT part from create data
+  const insertEntries: Array<{ dbName: string; value: unknown }> = [];
+  for (const [key, value] of Object.entries(create)) {
+    if (value === undefined) continue;
+    const sf = sfMap.get(key);
+    if (sf) {
+      insertEntries.push({ dbName: sf.dbName, value });
+    }
+  }
+
+  let paramIdx = 0;
+  const allValues: unknown[] = [];
+
+  const insertColumns = insertEntries.map((e) => `"${e.dbName}"`).join(", ");
+  const insertPlaceholders = insertEntries.map((e) => {
+    paramIdx++;
+    allValues.push(e.value);
+    return `$${paramIdx}`;
+  }).join(", ");
+
+  // Build UPDATE SET part from update data (using atomic operations)
+  const updateClauses: string[] = [];
+  for (const [key, value] of Object.entries(update)) {
+    if (value === undefined) continue;
+    const sf = sfMap.get(key);
+    if (!sf) continue;
+
+    const setResult = buildSetClause({
+      dbName: sf.dbName,
+      value,
+      paramIdx,
+    });
+    updateClauses.push(setResult.sql);
+    allValues.push(...setResult.values);
+    paramIdx += setResult.values.length;
+  }
+
+  const returningCols = modelMeta.scalarFields
+    .map((f) => `"${f.dbName}" AS "${f.name}"`)
+    .join(", ");
+
+  let text: string;
+  if (updateClauses.length > 0) {
+    text = `INSERT INTO ${table} (${insertColumns}) VALUES (${insertPlaceholders}) ON CONFLICT (${conflictCols.join(", ")}) DO UPDATE SET ${updateClauses.join(", ")} RETURNING ${returningCols}`;
+  } else {
+    text = `INSERT INTO ${table} (${insertColumns}) VALUES (${insertPlaceholders}) ON CONFLICT (${conflictCols.join(", ")}) DO NOTHING RETURNING ${returningCols}`;
+  }
+
+  return { text, values: allValues };
+}
+
+// ─── Column Resolution ────────────────────────────────────────────
+
+function resolveSelectColumns(params: {
+  modelMeta: ModelMeta;
+  args: Record<string, unknown>;
+}): readonly ScalarFieldMeta[] {
+  const { modelMeta, args } = params;
+  const select = args.select as Record<string, boolean | object> | undefined;
+  const omit = args.omit as Record<string, boolean> | undefined;
+
+  if (select) {
+    // With select → return only selected scalar fields
+    const columns = modelMeta.scalarFields.filter((f) => {
+      const val = select[f.name];
+      return val === true || (typeof val === "object" && val !== null);
+    });
+
+    // Auto-include PK if select has nested relations (needed for Phase 2 relation loading)
+    const hasNested = Object.entries(select).some(([key, val]) => {
+      if (typeof val !== "object" || val === null) return false;
+      return modelMeta.relationFields.some((r) => r.name === key);
+    });
+
+    if (hasNested) {
+      // Auto-include PK columns (needed for all relation loading strategies)
+      for (const pkName of modelMeta.primaryKey) {
+        if (!columns.some((c) => c.name === pkName)) {
+          const sf = modelMeta.scalarFields.find((f) => f.name === pkName);
+          if (sf) columns.push(sf);
+        }
+      }
+
+      // Auto-include FK fields for selected to-one relations where parent holds the FK
+      // (needed for Phase 2 relation loading to query related records by FK value)
+      for (const [key, val] of Object.entries(select)) {
+        if (typeof val !== "object" || val === null) continue;
+        const rel = modelMeta.relationFields.find((r) => r.name === key);
+        if (rel && rel.isForeignKey && !rel.isList) {
+          for (const fkFieldName of rel.fields) {
+            if (!columns.some((c) => c.name === fkFieldName)) {
+              const sf = modelMeta.scalarFields.find((f) => f.name === fkFieldName);
+              if (sf) columns.push(sf);
+            }
+          }
+        }
+      }
+    }
+
+    return columns;
+  }
+
+  if (omit) {
+    // With omit → return all scalar fields except omitted ones
+    return modelMeta.scalarFields.filter((f) => !omit[f.name]);
+  }
+
+  // No select/omit → return all scalar fields (default selection)
+  return modelMeta.scalarFields;
+}