@vibeorm/runtime 1.0.0

package/src/client.ts

@@ -0,0 +1,2055 @@
+/**
+ * VibeORM Client Runtime
+ *
+ * Creates the actual client instance that the generated code uses.
+ * This connects to PostgreSQL via a DatabaseAdapter and executes
+ * queries built by the query builder.
+ */
+
+import type {
+  VibeClientOptions,
+  ModelMeta,
+  ModelMetaMap,
+  ModelSchemas,
+  Operation,
+  QueryProfile,
+  ProfilingContext,
+} from "./types.ts";
+import { getScalarFieldMap, getModelByNameMap, PgArray } from "./types.ts";
+import type { DatabaseAdapter } from "./adapter.ts";
+import { VibeValidationError } from "./errors.ts";
+import {
+  buildSelectQuery,
+  buildInsertQuery,
+  buildInsertManyQuery,
+  buildUpdateQuery,
+  buildUpdateManyQuery,
+  buildDeleteQuery,
+  buildCountQuery,
+  buildAggregateQuery,
+  buildGroupByQuery,
+  buildUpsertQuery,
+} from "./query-builder.ts";
+import { loadRelations } from "./relation-loader.ts";
+import {
+  loadRelationsWithLateralJoin,
+  executeLateralJoinQuery,
+  resolveRelationsToLoad,
+} from "./lateral-join-builder.ts";
+import { generateDefault } from "./id-generators.ts";
+
+/**
+ * Creates a VibeORM client instance.
+ * Called by the generated index.ts file.
+ */
+export function createClient(params: {
+  options: VibeClientOptions;
+  modelMeta: Record<string, ModelMeta>;
+  schemas?: Record<string, ModelSchemas>;
+}): Record<string, unknown> {
+  const { options, modelMeta } = params;
+  const adapter = options.adapter;
+  const shouldLog = options?.log === true || options?.log === "query";
+  const shouldDebug = !!options?.debug;
+
+  /** Emit a query profile to the user's debug handler or console. */
+  function debugEmit(profile: QueryProfile): void {
+    if (!shouldDebug) return;
+    if (typeof options?.debug === "function") {
+      options.debug({ profile });
+    } else {
+      // Pretty-print to console
+      const pad = (s: string, n: number) => s.padEnd(n);
+      console.log(
+        `[vibeorm:debug] ${profile.model}.${profile.operation} — ${profile.totalMs.toFixed(2)}ms total`
+      );
+      console.log(
+        `  query build:    ${profile.queryBuildMs.toFixed(2)}ms`
+      );
+      console.log(
+        `  sql exec:       ${profile.sqlExecMs.toFixed(2)}ms  (${profile.rowCount} rows)`
+      );
+      if (profile.resultMapMs > 0) {
+        console.log(
+          `  result map:     ${profile.resultMapMs.toFixed(2)}ms`
+        );
+      }
+      if (profile.relationLoadMs > 0) {
+        console.log(
+          `  relation load:  ${profile.relationLoadMs.toFixed(2)}ms`
+        );
+        for (const rp of profile.relationProfiles) {
+          console.log(
+            `    ${pad(rp.relation + ":", 20)} ${rp.sqlExecMs.toFixed(2)}ms  (${rp.rowCount} rows)`
+          );
+        }
+      }
+      if (profile.resultSizeBytes > 0) {
+        const kb = (profile.resultSizeBytes / 1024).toFixed(1);
+        console.log(`  result size:    ~${kb} KB`);
+      }
+      console.log(`  SQL: ${profile.sql.slice(0, 200)}${profile.sql.length > 200 ? "..." : ""}`);
+      console.log("");
+    }
+  }
+
+  /** Fast approximate result size in bytes (avoids full JSON.stringify). */
+  function estimateResultSize(params: { records: Record<string, unknown>[] }): number {
+    let size = 0;
+    for (const record of params.records) {
+      for (const key in record) {
+        const val = record[key];
+        size += key.length;
+        if (val === null || val === undefined) {
+          size += 4;
+        } else if (typeof val === "string") {
+          size += val.length;
+        } else if (typeof val === "number" || typeof val === "boolean") {
+          size += 8;
+        } else if (val instanceof Date) {
+          size += 24;
+        } else if (Array.isArray(val)) {
+          // Rough estimate for relation arrays: count items * avg row size
+          size += val.length * 200;
+        } else if (typeof val === "object") {
+          size += 200; // rough estimate for nested objects
+        }
+      }
+    }
+    return size;
+  }
+
+  /** Create a profiling-aware executor that records per-call SQL timing. */
+  function createProfiledExecutor(profilingCtx: ProfilingContext): {
+    executor: typeof executeSql;
+    getTimings: () => { totalExecMs: number; calls: number };
+  } {
+    let totalExecMs = 0;
+    let calls = 0;
+
+    const executor = async (execParams: {
+      text: string;
+      values: unknown[];
+    }): Promise<Record<string, unknown>[]> => {
+      const t0 = performance.now();
+      const result = await executeSql(execParams);
+      const elapsed = performance.now() - t0;
+      totalExecMs += elapsed;
+      calls++;
+
+      // Record as a relation profile if this is a sub-query (not the main query)
+      // The main query is handled separately; relation queries are tracked via
+      // the profilingCtx being passed through loadRelations.
+      return result;
+    };
+
+    return {
+      executor,
+      getTimings: () => ({ totalExecMs, calls }),
+    };
+  }
+
+  // Normalize model meta into a lookup by camelCase name
+  const allModelsMeta: ModelMetaMap = {};
+  for (const [key, meta] of Object.entries(modelMeta)) {
+    allModelsMeta[key] = meta;
+  }
+
+  // SQL executor function — delegates to the adapter.
+  // Array values are converted via adapter.formatArrayParam so that
+  // = ANY($1) works correctly.
+  async function executeSql(params: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]> {
+    const { text, values: rawValues } = params;
+    // Convert PgArray instances - let the adapter handle the format
+    const values = rawValues.map((v) => (v instanceof PgArray ? adapter.formatArrayParam(v.values) : v));
+
+    if (shouldLog) {
+      console.log(`[vibeorm] ${text}`);
+      if (values.length > 0) {
+        console.log(`[vibeorm] params:`, values);
+      }
+    }
+
+    return adapter.execute({ text, values });
+  }
+
+  // Create delegate for a model
+  function createDelegate(params: {
+    modelKey: string;
+    modelMeta: ModelMeta;
+    executor: typeof executeSql;
+    schemas?: ModelSchemas;
+  }): Record<string, Function> {
+    const { modelKey, modelMeta, executor, schemas } = params;
+
+    // Resolve validation mode from options
+    const validateOpt = options?.validate;
+    const shouldValidateInput = !!schemas && (
+      validateOpt === true || validateOpt === "all" || validateOpt === "input"
+    );
+    const shouldValidateOutput = !!schemas && (
+      validateOpt === true || validateOpt === "all" || validateOpt === "output"
+    );
+
+    function validateInput(innerParams: {
+      data: unknown;
+      schemaKey: keyof ModelSchemas;
+      operation: string;
+    }): void {
+      if (!shouldValidateInput) return;
+      const schema = schemas?.[innerParams.schemaKey];
+      if (!schema) return;
+      const result = schema.safeParse(innerParams.data);
+      if (!result.success) {
+        throw new VibeValidationError({
+          model: modelMeta.name,
+          operation: innerParams.operation,
+          direction: "input",
+          zodError: result.error,
+        });
+      }
+    }
+
+    function validateOutput(innerParams: {
+      records: Record<string, unknown>[];
+      operation: string;
+    }): void {
+      if (!shouldValidateOutput) return;
+      const schema = schemas?.model;
+      if (!schema) return;
+      for (const record of innerParams.records) {
+        const result = schema.safeParse(record);
+        if (!result.success) {
+          throw new VibeValidationError({
+            model: modelMeta.name,
+            operation: innerParams.operation,
+            direction: "output",
+            zodError: result.error,
+          });
+        }
+      }
+    }
+
+    function shouldUseLateralJoin(args: Record<string, unknown>): boolean {
+      const strategy =
+        (args.relationStrategy as string) ??
+        options?.relationStrategy ??
+        "query";
+      if (strategy !== "join") return false;
+      // Only use lateral join if there are relations to load
+      const rels = resolveRelationsToLoad({ parentModelMeta: modelMeta, args });
+      return rels.length > 0;
+    }
+
+    async function findMany(args: Record<string, unknown> = {}) {
+      if (shouldUseLateralJoin(args)) {
+        if (shouldDebug) {
+          const profilingCtx: ProfilingContext = { relationProfiles: [] };
+          const t0 = performance.now();
+          const result = await executeLateralJoinQuery({
+            modelMeta,
+            allModelsMeta,
+            args,
+            executor: executeSql,
+            profilingCtx,
+          });
+          const t1 = performance.now();
+          const sizeBytes = estimateResultSize({ records: result });
+          debugEmit({
+            model: modelMeta.name,
+            operation: "findMany",
+            totalMs: t1 - t0,
+            queryBuildMs: profilingCtx.queryBuildMs ?? 0,
+            sqlExecMs: profilingCtx.sqlExecMs ?? 0,
+            rowCount: result.length,
+            relationLoadMs: 0,
+            relationProfiles: profilingCtx.relationProfiles,
+            sql: profilingCtx.sql ?? "(lateral join)",
+            resultMapMs: profilingCtx.resultMapMs ?? 0,
+            resultSizeBytes: sizeBytes,
+            sqlValues: profilingCtx.sqlValues,
+          });
+          validateOutput({ records: result, operation: "findMany" });
+          return result;
+        }
+
+        const result = await executeLateralJoinQuery({
+          modelMeta,
+          allModelsMeta,
+          args,
+          executor,
+        });
+        validateOutput({ records: result, operation: "findMany" });
+        return result;
+      }
+
+      if (shouldDebug) {
+        const profilingCtx: ProfilingContext = { relationProfiles: [] };
+        const { executor: profExec } = createProfiledExecutor(profilingCtx);
+        const t0 = performance.now();
+        const query = buildSelectQuery({
+          modelMeta,
+          allModelsMeta,
+          args,
+        });
+        const t1 = performance.now();
+        let records = await profExec(query);
+        const t2 = performance.now();
+        records = await loadRelationsForStrategy({
+          records,
+          modelMeta,
+          allModelsMeta,
+          args,
+          executor: profExec,
+          profilingCtx,
+        });
+        const t3 = performance.now();
+        const sizeBytes = estimateResultSize({ records });
+        debugEmit({
+          model: modelMeta.name,
+          operation: "findMany",
+          totalMs: t3 - t0,
+          queryBuildMs: t1 - t0,
+          sqlExecMs: t2 - t1,
+          rowCount: records.length,
+          relationLoadMs: t3 - t2,
+          relationProfiles: profilingCtx.relationProfiles,
+          sql: query.text,
+          resultMapMs: 0,
+          resultSizeBytes: sizeBytes,
+        });
+        records = applySelectFiltering({ records, args, modelMeta });
+        validateOutput({ records, operation: "findMany" });
+        return records;
+      }
+
+      const query = buildSelectQuery({
+        modelMeta,
+        allModelsMeta,
+        args,
+      });
+      let records = await executor(query);
+
+      records = await loadRelationsForStrategy({
+        records,
+        modelMeta,
+        allModelsMeta,
+        args,
+        executor,
+      });
+
+      records = applySelectFiltering({ records, args, modelMeta });
+      validateOutput({ records, operation: "findMany" });
+      return records;
+    }
+
+    async function findFirst(args: Record<string, unknown> = {}) {
+      const argsWithLimit = { ...args, take: 1 };
+
+      if (shouldUseLateralJoin(args)) {
+        const records = await executeLateralJoinQuery({
+          modelMeta,
+          allModelsMeta,
+          args: argsWithLimit,
+          executor,
+        });
+        validateOutput({ records, operation: "findFirst" });
+        return records[0] ?? null;
+      }
+
+      if (shouldDebug) {
+        const profilingCtx: ProfilingContext = { relationProfiles: [] };
+        const { executor: profExec } = createProfiledExecutor(profilingCtx);
+        const t0 = performance.now();
+        const query = buildSelectQuery({ modelMeta, allModelsMeta, args: argsWithLimit });
+        const t1 = performance.now();
+        let records = await profExec(query);
+        const t2 = performance.now();
+        records = await loadRelationsForStrategy({
+          records, modelMeta, allModelsMeta, args, executor: profExec, profilingCtx,
+        });
+        const t3 = performance.now();
+        debugEmit({
+          model: modelMeta.name, operation: "findFirst",
+          totalMs: t3 - t0, queryBuildMs: t1 - t0, sqlExecMs: t2 - t1,
+          rowCount: records.length, relationLoadMs: t3 - t2,
+          relationProfiles: profilingCtx.relationProfiles, sql: query.text,
+          resultMapMs: 0, resultSizeBytes: estimateResultSize({ records }),
+        });
+        records = applySelectFiltering({ records, args, modelMeta });
+        validateOutput({ records, operation: "findFirst" });
+        return records[0] ?? null;
+      }
+
+      const query = buildSelectQuery({
+        modelMeta,
+        allModelsMeta,
+        args: argsWithLimit,
+      });
+      let records = await executor(query);
+
+      records = await loadRelationsForStrategy({
+        records,
+        modelMeta,
+        allModelsMeta,
+        args,
+        executor,
+      });
+
+      records = applySelectFiltering({ records, args, modelMeta });
+      validateOutput({ records, operation: "findFirst" });
+      return records[0] ?? null;
+    }
+
+    async function findUnique(args: Record<string, unknown>) {
+      // Expand compound unique keys: { userId_planId: { userId: 1, planId: 2 } } → { userId: 1, planId: 2 }
+      if (args.where) {
+        args = { ...args, where: convertUniqueToWhere({ uniqueWhere: args.where as Record<string, unknown>, modelMeta }) };
+      }
+      const argsWithLimit = { ...args, take: 1 };
+
+      if (shouldUseLateralJoin(args)) {
+        const records = await executeLateralJoinQuery({
+          modelMeta,
+          allModelsMeta,
+          args: argsWithLimit,
+          executor,
+        });
+        validateOutput({ records, operation: "findUnique" });
+        return records[0] ?? null;
+      }
+
+      if (shouldDebug) {
+        const profilingCtx: ProfilingContext = { relationProfiles: [] };
+        const { executor: profExec } = createProfiledExecutor(profilingCtx);
+        const t0 = performance.now();
+        const query = buildSelectQuery({ modelMeta, allModelsMeta, args: argsWithLimit });
+        const t1 = performance.now();
+        let records = await profExec(query);
+        const t2 = performance.now();
+        records = await loadRelationsForStrategy({
+          records, modelMeta, allModelsMeta, args, executor: profExec, profilingCtx,
+        });
+        const t3 = performance.now();
+        debugEmit({
+          model: modelMeta.name, operation: "findUnique",
+          totalMs: t3 - t0, queryBuildMs: t1 - t0, sqlExecMs: t2 - t1,
+          rowCount: records.length, relationLoadMs: t3 - t2,
+          relationProfiles: profilingCtx.relationProfiles, sql: query.text,
+          resultMapMs: 0, resultSizeBytes: estimateResultSize({ records }),
+        });
+        records = applySelectFiltering({ records, args, modelMeta });
+        validateOutput({ records, operation: "findUnique" });
+        return records[0] ?? null;
+      }
+
+      const query = buildSelectQuery({
+        modelMeta,
+        allModelsMeta,
+        args: argsWithLimit,
+      });
+      let records = await executor(query);
+
+      records = await loadRelationsForStrategy({
+        records,
+        modelMeta,
+        allModelsMeta,
+        args,
+        executor,
+      });
+
+      records = applySelectFiltering({ records, args, modelMeta });
+      validateOutput({ records, operation: "findUnique" });
+      return records[0] ?? null;
+    }
+
+    async function findUniqueOrThrow(args: Record<string, unknown>) {
+      const result = await findUnique(args);
+      if (!result) {
+        throw new Error(
+          `No ${modelMeta.name} found for the given where clause`
+        );
+      }
+      return result;
+    }
+
+    async function findFirstOrThrow(args: Record<string, unknown> = {}) {
+      const result = await findFirst(args);
+      if (!result) {
+        throw new Error(
+          `No ${modelMeta.name} found for the given where clause`
+        );
+      }
+      return result;
+    }
+
+    async function create(args: Record<string, unknown>) {
+      const data = args.data as Record<string, unknown>;
+
+      // Validate input
+      validateInput({ data, schemaKey: "createInput", operation: "create" });
+
+      // Auto-inject @updatedAt fields and auto-generated defaults (uuid, cuid, etc.)
+      injectUpdatedAt({ data, modelMeta });
+      injectAutoDefaults({ data, modelMeta, idGenerator: options?.idGenerator });
+
+      const { processedData, deferredCreates } = await processNestedCreates({
+        data,
+        modelMeta,
+        allModelsMeta,
+        executor,
+      });
+
+      const query = buildInsertQuery({
+        modelMeta,
+        data: processedData,
+      });
+      let records = await executor(query);
+
+      // Execute deferred creates (related records that hold the FK to this parent)
+      // Group by related model to batch multiple creates into single INSERT statements.
+      const parentRecord = records[0];
+      if (parentRecord && deferredCreates.length > 0) {
+        for (const deferred of deferredCreates) {
+          const parentRefValue = parentRecord[deferred.parentRefField];
+          if (parentRefValue != null) {
+            const createItems = Array.isArray(deferred.createData) ? deferred.createData : [deferred.createData];
+            const dataArray = createItems.map((createData) => {
+              (createData as Record<string, unknown>)[deferred.fkField] = parentRefValue;
+              return createData as Record<string, unknown>;
+            });
+            if (dataArray.length === 1) {
+              const insertQuery = buildInsertQuery({ modelMeta: deferred.relatedModelMeta, data: dataArray[0]! });
+              await executor(insertQuery);
+            } else if (dataArray.length > 1) {
+              const insertQuery = buildInsertManyQuery({ modelMeta: deferred.relatedModelMeta, data: dataArray, returning: false });
+              await executor(insertQuery);
+            }
+          }
+        }
+      }
+
+      records = await loadRelationsForStrategy({
+        records,
+        modelMeta,
+        allModelsMeta,
+        args,
+        executor,
+      });
+
+      records = applySelectFiltering({ records, args, modelMeta });
+
+      validateOutput({ records, operation: "create" });
+      return records[0]!;
+    }
+
+    async function update(args: Record<string, unknown>) {
+      const where = args.where as Record<string, unknown>;
+      const data = args.data as Record<string, unknown>;
+
+      // Validate input
+      validateInput({ data, schemaKey: "updateInput", operation: "update" });
+
+      // Auto-inject @updatedAt fields
+      injectUpdatedAt({ data, modelMeta });
+
+      const whereInput = convertUniqueToWhere({
+        uniqueWhere: where,
+        modelMeta,
+      });
+
+      // Separate scalar data from nested relation operations
+      const { scalarData, nestedOps } = separateNestedOps({
+        data,
+        modelMeta,
+      });
+
+      const query = buildUpdateQuery({
+        modelMeta,
+        allModelsMeta,
+        where: whereInput,
+        data: scalarData,
+      });
+      let records = await executor(query);
+
+      if (records.length === 0) {
+        throw new Error(
+          `An operation failed because it depends on one or more records that were required but not found. No ${modelMeta.name} found for the given where clause.`
+        );
+      }
+
+      const updatedRecord = records[0]!;
+
+      // Process nested relation operations
+      if (nestedOps.length > 0) {
+        await processNestedUpdateOps({
+          parentRecord: updatedRecord,
+          nestedOps,
+          modelMeta,
+          allModelsMeta,
+          executor,
+        });
+      }
+
+      records = await loadRelationsForStrategy({
+        records,
+        modelMeta,
+        allModelsMeta,
+        args,
+        executor,
+      });
+
+      records = applySelectFiltering({ records, args, modelMeta });
+
+      validateOutput({ records, operation: "update" });
+      return records[0]!;
+    }
+
+    async function upsert(args: Record<string, unknown>) {
+      const where = args.where as Record<string, unknown>;
+      const createData = args.create as Record<string, unknown>;
+      const updateData = args.update as Record<string, unknown>;
+
+      // Validate inputs
+      validateInput({ data: createData, schemaKey: "createInput", operation: "upsert" });
+      validateInput({ data: updateData, schemaKey: "updateInput", operation: "upsert" });
+
+      // Auto-inject @updatedAt fields and auto-generated defaults for create data
+      injectUpdatedAt({ data: createData, modelMeta });
+      injectUpdatedAt({ data: updateData, modelMeta });
+      injectAutoDefaults({ data: createData, modelMeta, idGenerator: options?.idGenerator });
+
+      const whereInput = convertUniqueToWhere({
+        uniqueWhere: where,
+        modelMeta,
+      });
+
+      const query = buildUpsertQuery({
+        modelMeta,
+        where: whereInput,
+        create: createData,
+        update: updateData,
+      });
+
+      let records = await executor(query);
+
+      // If ON CONFLICT DO NOTHING returned no rows (rare edge case),
+      // fall back to reading the existing record
+      if (records.length === 0) {
+        const existing = await findUnique({ where, select: args.select, include: args.include });
+        if (existing) return existing;
+        throw new Error(`Upsert failed: could not insert or find ${modelMeta.name}`);
+      }
+
+      records = await loadRelationsForStrategy({
+        records,
+        modelMeta,
+        allModelsMeta,
+        args,
+        executor,
+      });
+
+      records = applySelectFiltering({ records, args, modelMeta });
+
+      validateOutput({ records, operation: "upsert" });
+      return records[0]!;
+    }
+
+    async function del(args: Record<string, unknown>) {
+      const where = args.where as Record<string, unknown>;
+      const whereInput = convertUniqueToWhere({
+        uniqueWhere: where,
+        modelMeta,
+      });
+
+      const query = buildDeleteQuery({
+        modelMeta,
+        allModelsMeta,
+        where: whereInput,
+      });
+      let records = await executor(query);
+
+      if (records.length === 0) {
+        throw new Error(
+          `An operation failed because it depends on one or more records that were required but not found. No ${modelMeta.name} found for the given where clause.`
+        );
+      }
+
+      coerceFieldTypes({ records, modelMeta });
+      records = applySelectFiltering({ records, args, modelMeta });
+
+      validateOutput({ records, operation: "delete" });
+      return records[0]!;
+    }
+
+    async function deleteMany(args: Record<string, unknown> = {}) {
+      const where = (args.where ?? {}) as Record<string, unknown>;
+      // Use a CTE with RETURNING 1 to count deleted rows server-side
+      // instead of transferring full row payloads over the wire.
+      const baseQuery = buildDeleteQuery({
+        modelMeta,
+        allModelsMeta,
+        where,
+      });
+      // Replace RETURNING <all cols> with RETURNING 1 inside a CTE
+      const returningIdx = baseQuery.text.indexOf(" RETURNING ");
+      const deleteText = returningIdx >= 0 ? baseQuery.text.slice(0, returningIdx) : baseQuery.text;
+      const countQuery = {
+        text: `WITH deleted AS (${deleteText} RETURNING 1) SELECT COUNT(*) AS "count" FROM deleted`,
+        values: baseQuery.values,
+      };
+      const result = await executor(countQuery);
+      const row = result[0] as { count: string | number } | undefined;
+      return { count: Number(row?.count ?? 0) };
+    }
+
+    async function count(args: Record<string, unknown> = {}) {
+      const countStrategy = options?.countStrategy ?? "direct";
+
+      if (shouldDebug) {
+        const t0 = performance.now();
+        const query = buildCountQuery({ modelMeta, allModelsMeta, args, countStrategy });
+        const t1 = performance.now();
+        const records = await executor(query);
+        const t2 = performance.now();
+        const row = records[0] as { count: string | number } | undefined;
+        debugEmit({
+          model: modelMeta.name, operation: "count",
+          totalMs: t2 - t0, queryBuildMs: t1 - t0, sqlExecMs: t2 - t1,
+          rowCount: 1, relationLoadMs: 0, relationProfiles: [], sql: query.text,
+          resultMapMs: 0, resultSizeBytes: 0,
+        });
+        return Number(row?.count ?? 0);
+      }
+
+      const query = buildCountQuery({
+        modelMeta,
+        allModelsMeta,
+        args,
+        countStrategy,
+      });
+      const records = await executor(query);
+      const row = records[0] as { count: string | number } | undefined;
+      return Number(row?.count ?? 0);
+    }
+
+    async function createMany(args: Record<string, unknown>) {
+      const rawData = args.data as Record<string, unknown> | Record<string, unknown>[];
+      const dataArray = Array.isArray(rawData) ? rawData : [rawData];
+
+      // Short-circuit: empty data array → no rows inserted
+      if (dataArray.length === 0) {
+        return { count: 0 };
+      }
+
+      // Validate inputs
+      for (const record of dataArray) {
+        validateInput({ data: record, schemaKey: "createInput", operation: "createMany" });
+      }
+
+      // Auto-inject @updatedAt fields and auto-generated defaults on each record
+      for (const record of dataArray) {
+        injectUpdatedAt({ data: record, modelMeta });
+        injectAutoDefaults({ data: record, modelMeta, idGenerator: options?.idGenerator });
+      }
+
+      // Count inserted rows server-side using CTE with RETURNING 1.
+      // This avoids transferring PK values over the wire just to count them.
+      // Handles skipDuplicates correctly since ON CONFLICT DO NOTHING rows
+      // won't appear in the RETURNING set.
+      const query = buildInsertManyQuery({
+        modelMeta,
+        data: dataArray,
+        skipDuplicates: args.skipDuplicates as boolean | undefined,
+        returning: true,
+        selectFields: [modelMeta.primaryKey[0]!],
+      });
+      // Wrap in CTE to count server-side
+      const returningIdx = query.text.indexOf(" RETURNING ");
+      if (returningIdx >= 0) {
+        const insertText = query.text.slice(0, returningIdx);
+        const countQuery = {
+          text: `WITH inserted AS (${insertText} RETURNING 1) SELECT COUNT(*) AS "count" FROM inserted`,
+          values: query.values,
+        };
+        const result = await executor(countQuery);
+        const row = result[0] as { count: string | number } | undefined;
+        return { count: Number(row?.count ?? 0) };
+      }
+      // Fallback: if no RETURNING clause (shouldn't happen), execute as-is
+      const result = await executor(query);
+      return { count: result.length };
+    }
+
+    async function createManyAndReturn(args: Record<string, unknown>) {
+      const rawData = args.data as Record<string, unknown> | Record<string, unknown>[];
+      const dataArray = Array.isArray(rawData) ? rawData : [rawData];
+
+      // Short-circuit: empty data array → no rows inserted
+      if (dataArray.length === 0) {
+        return [];
+      }
+
+      // Validate inputs
+      for (const record of dataArray) {
+        validateInput({ data: record, schemaKey: "createInput", operation: "createManyAndReturn" });
+      }
+
+      // Auto-inject @updatedAt fields and auto-generated defaults on each record
+      for (const record of dataArray) {
+        injectUpdatedAt({ data: record, modelMeta });
+        injectAutoDefaults({ data: record, modelMeta, idGenerator: options?.idGenerator });
+      }
+
+      const query = buildInsertManyQuery({
+        modelMeta,
+        data: dataArray,
+        skipDuplicates: args.skipDuplicates as boolean | undefined,
+        returning: true,
+      });
+      let records = await executor(query);
+
+      records = await loadRelationsForStrategy({
+        records,
+        modelMeta,
+        allModelsMeta,
+        args,
+        executor,
+      });
+
+      records = applySelectFiltering({ records, args, modelMeta });
+
+      validateOutput({ records, operation: "createManyAndReturn" });
+      return records;
+    }
+
+    async function updateMany(args: Record<string, unknown>) {
+      const where = (args.where ?? {}) as Record<string, unknown>;
+      const data = args.data as Record<string, unknown>;
+
+      // Validate input
+      validateInput({ data, schemaKey: "updateInput", operation: "updateMany" });
+
+      // Short-circuit: if user provided no data fields, return 0 immediately
+      // (check BEFORE injectUpdatedAt so auto-managed fields don't cause a real UPDATE)
+      const userDataKeys = Object.keys(data).filter((k) => data[k] !== undefined);
+      if (userDataKeys.length === 0) {
+        return { count: 0 };
+      }
+
+      // Auto-inject @updatedAt fields
+      injectUpdatedAt({ data, modelMeta });
+
+      const query = buildUpdateManyQuery({
+        modelMeta,
+        allModelsMeta,
+        where,
+        data,
+      });
+
+      // Short-circuit: if builder returned a no-op (empty data), return 0 directly
+      // This avoids wrapping `SELECT 0 AS "count"` in an invalid CTE with RETURNING
+      if (query.text.startsWith("SELECT 0")) {
+        return { count: 0 };
+      }
+
+      // updateMany without RETURNING — we need row count
+      // Use a CTE with RETURNING trick to get count
+      const countQuery = {
+        text: `WITH updated AS (${query.text} RETURNING 1) SELECT COUNT(*) AS "count" FROM updated`,
+        values: query.values,
+      };
+      const result = await executor(countQuery);
+      const row = result[0] as { count: string | number } | undefined;
+      return { count: Number(row?.count ?? 0) };
+    }
+
+    async function aggregate(args: Record<string, unknown>) {
+      const query = buildAggregateQuery({
+        modelMeta,
+        allModelsMeta,
+        args,
+      });
+      const records = await executor(query);
+      const row = records[0] as Record<string, unknown> | undefined;
+
+      if (!row) {
+        return {};
+      }
+
+      // Transform flat row with keys like "_count__all", "_avg__viewCount"
+      // into nested structure: { _count: 5, _avg: { viewCount: 45.2 } }
+      return parseAggregateResult({ row, args });
+    }
+
+    async function groupBy(args: Record<string, unknown>) {
+      const query = buildGroupByQuery({
+        modelMeta,
+        allModelsMeta,
+        args,
+      });
+      const records = await executor(query);
+
+      // Transform each row's flat aggregate columns into nested structure
+      return records.map((row) => parseAggregateResult({ row, args }));
+    }
+
+    return {
+      findMany,
+      findFirst,
+      findUnique,
+      findUniqueOrThrow,
+      findFirstOrThrow,
+      create,
+      createMany,
+      createManyAndReturn,
+      update,
+      upsert,
+      delete: del,
+      deleteMany,
+      updateMany,
+      count,
+      aggregate,
+      groupBy,
+    };
+  }
+
+  // Helper: load relations using the configured strategy
+  async function loadRelationsForStrategy(params: {
+    records: Record<string, unknown>[];
+    modelMeta: ModelMeta;
+    allModelsMeta: ModelMetaMap;
+    args: Record<string, unknown>;
+    executor: typeof executeSql;
+    profilingCtx?: ProfilingContext;
+  }): Promise<Record<string, unknown>[]> {
+    // Coerce field types (e.g., BigInt from string) before any processing
+    coerceFieldTypes({ records: params.records, modelMeta: params.modelMeta });
+
+    const strategy =
+      (params.args.relationStrategy as string) ??
+      options?.relationStrategy ??
+      "query";
+
+    let records: Record<string, unknown>[];
+    if (strategy === "join") {
+      records = await loadRelationsWithLateralJoin({
+        parentRecords: params.records,
+        parentModelMeta: params.modelMeta,
+        allModelsMeta: params.allModelsMeta,
+        args: params.args,
+        executor: params.executor,
+        profilingCtx: params.profilingCtx,
+      });
+    } else {
+      records = await loadRelations({
+        parentRecords: params.records,
+        parentModelMeta: params.modelMeta,
+        allModelsMeta: params.allModelsMeta,
+        args: params.args,
+        executor: params.executor,
+        profilingCtx: params.profilingCtx,
+      });
+    }
+
+    // Load _count if requested in include or select
+    const countSpec = resolveCountSpec({ args: params.args });
+    if (countSpec && records.length > 0) {
+      await loadRelationCounts({
+        records,
+        modelMeta: params.modelMeta,
+        allModelsMeta: params.allModelsMeta,
+        countSpec,
+        executor: params.executor,
+      });
+    }
+
+    return records;
+  }
+
+  // Build the client object with delegates for each model
+  const client: Record<string, unknown> = {};
+
+  for (const [key, meta] of Object.entries(allModelsMeta)) {
+    client[key] = createDelegate({
+      modelKey: key,
+      modelMeta: meta,
+      executor: executeSql,
+      schemas: params.schemas?.[key],
+    });
+  }
+
+  // $transaction — supports both callback style and array-of-promises style
+  client.$transaction = async function <T>(
+    fnOrPromises: ((tx: Record<string, unknown>) => Promise<T>) | Promise<unknown>[]
+  ): Promise<T | unknown[]> {
+    // Array-of-promises style
+    if (Array.isArray(fnOrPromises)) {
+      return adapter.transaction(async () => {
+        return Promise.all(fnOrPromises);
+      });
+    }
+
+    // Callback style
+    const fn = fnOrPromises as (tx: Record<string, unknown>) => Promise<T>;
+    return adapter.transaction(async (txAdapter) => {
+      // Create a transactional executor
+      async function txExecutor(txParams: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]> {
+        const values = txParams.values.map((v) => (v instanceof PgArray ? txAdapter.formatArrayParam(v.values) : v));
+        if (shouldLog) {
+          console.log(`[vibeorm:tx] ${txParams.text}`);
+          if (values.length > 0) {
+            console.log(`[vibeorm:tx] params:`, values);
+          }
+        }
+        return txAdapter.execute({ text: txParams.text, values });
+      }
+
+      // Build transactional delegates
+      const txClient: Record<string, unknown> = {};
+      for (const [key, meta] of Object.entries(allModelsMeta)) {
+        txClient[key] = createDelegate({
+          modelKey: key,
+          modelMeta: meta,
+          executor: txExecutor,
+          schemas: params.schemas?.[key],
+        });
+      }
+
+      // Add $queryRaw and $executeRaw to transactional client
+      txClient.$queryRaw = async function <T = unknown>(
+        strings: TemplateStringsArray,
+        ...values: unknown[]
+      ): Promise<T[]> {
+        const { text, params: sqlParams } = buildTaggedTemplateSql({ strings, values });
+        if (shouldLog) {
+          console.log(`[vibeorm:tx] ${text}`);
+          if (sqlParams.length > 0) console.log(`[vibeorm:tx] params:`, sqlParams);
+        }
+        const result = await txAdapter.executeUnsafe({ text, values: sqlParams });
+        return result.rows as T[];
+      };
+
+      txClient.$executeRaw = async function (
+        strings: TemplateStringsArray,
+        ...values: unknown[]
+      ): Promise<number> {
+        const { text, params: sqlParams } = buildTaggedTemplateSql({ strings, values });
+        if (shouldLog) {
+          console.log(`[vibeorm:tx] ${text}`);
+          if (sqlParams.length > 0) console.log(`[vibeorm:tx] params:`, sqlParams);
+        }
+        const result = await txAdapter.executeUnsafe({ text, values: sqlParams });
+        return result.affectedRows;
+      };
+
+      return fn(txClient);
+    });
+  };
+
+  // $queryRaw — tagged template literal for safe parameterized queries
+  client.$queryRaw = async function <T = unknown>(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<T[]> {
+    const { text, params: sqlParams } = buildTaggedTemplateSql({ strings, values });
+    if (shouldLog) {
+      console.log(`[vibeorm:raw] ${text}`);
+      if (sqlParams.length > 0) {
+        console.log(`[vibeorm:raw] params:`, sqlParams);
+      }
+    }
+    const result = await adapter.executeUnsafe({ text, values: sqlParams });
+    return result.rows as T[];
+  };
+
+  // $executeRaw — tagged template literal for INSERT/UPDATE/DELETE returning affected count
+  client.$executeRaw = async function (
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<number> {
+    const { text, params: sqlParams } = buildTaggedTemplateSql({ strings, values });
+    if (shouldLog) {
+      console.log(`[vibeorm:raw] ${text}`);
+      if (sqlParams.length > 0) {
+        console.log(`[vibeorm:raw] params:`, sqlParams);
+      }
+    }
+    const result = await adapter.executeUnsafe({ text, values: sqlParams });
+    return result.affectedRows;
+  };
+
+  // $queryRawUnsafe — accepts a plain SQL string + params array
+  client.$queryRawUnsafe = async function <T = unknown>(
+    query: string,
+    ...values: unknown[]
+  ): Promise<T[]> {
+    if (shouldLog) {
+      console.log(`[vibeorm:raw] ${query}`);
+      if (values.length > 0) {
+        console.log(`[vibeorm:raw] params:`, values);
+      }
+    }
+    if (values.length === 0) {
+      const result = await adapter.executeUnsafe({ text: query });
+      return result.rows as T[];
+    }
+    const rows = await adapter.execute({ text: query, values });
+    return rows as T[];
+  };
+
+  // $executeRawUnsafe — accepts a plain SQL string + params array, returns affected count
+  client.$executeRawUnsafe = async function (
+    query: string,
+    ...values: unknown[]
+  ): Promise<number> {
+    if (shouldLog) {
+      console.log(`[vibeorm:raw] ${query}`);
+      if (values.length > 0) {
+        console.log(`[vibeorm:raw] params:`, values);
+      }
+    }
+    const result = await adapter.executeUnsafe({ text: query, values: values.length > 0 ? values : undefined });
+    return result.affectedRows;
+  };
+
+  // $connect
+  client.$connect = async function (): Promise<void> {
+    await adapter.connect();
+  };
+
+  // $disconnect
+  client.$disconnect = async function (): Promise<void> {
+    await adapter.disconnect();
+  };
+
+  // Eager connection: warm up the pool immediately on client creation.
+  // This runs in the background — it won't block client construction,
+  // but will ensure connections are ready before the first real query.
+  if (options.eager) {
+    adapter.connect().catch(() => {
+      // Swallow connection errors during eager warmup.
+      // They'll surface on the first actual query instead.
+    });
+  }
+
+  return client;
+}
+
+/**
+ * Coerce scalar field values to their correct JS types.
+ * Currently handles BigInt fields: bun:sql returns PostgreSQL bigint as string,
+ * but the application expects native BigInt values.
+ */
+function coerceFieldTypes(params: {
+  records: Record<string, unknown>[];
+  modelMeta: ModelMeta;
+}): Record<string, unknown>[] {
+  const { records, modelMeta } = params;
+  if (records.length === 0) return records;
+
+  // Find fields that need coercion
+  const bigintFields = modelMeta.scalarFields.filter(
+    (f) => (f as { type?: string }).type === "BigInt"
+  );
+
+  if (bigintFields.length === 0) return records;
+
+  for (const record of records) {
+    for (const field of bigintFields) {
+      const val = record[field.name];
+      if (typeof val === "string") {
+        record[field.name] = BigInt(val);
+      } else if (typeof val === "number") {
+        record[field.name] = BigInt(val);
+      }
+    }
+  }
+
+  return records;
+}
+
+/**
+ * Apply select filtering to returned records.
+ * When args.select is specified, strips fields not in the select object
+ * from each record. This ensures mutation results (create, update, delete, upsert)
+ * only contain the selected scalar fields (plus any relation fields loaded separately).
+ */
+function applySelectFiltering(params: {
+  records: Record<string, unknown>[];
+  args: Record<string, unknown>;
+  modelMeta: ModelMeta;
+}): Record<string, unknown>[] {
+  const { records, args, modelMeta } = params;
+  const select = args.select as Record<string, boolean | object> | undefined;
+  if (!select) return records;
+
+  // Build set of allowed scalar field names
+  const allowedFields = new Set<string>();
+  for (const [key, val] of Object.entries(select)) {
+    if (val === true || (typeof val === "object" && val !== null)) {
+      allowedFields.add(key);
+    }
+  }
+
+  // Also allow relation fields that were loaded (they won't be in scalarFields)
+  const scalarFieldNames = new Set(modelMeta.scalarFields.map((f) => f.name));
+
+  return records.map((record) => {
+    const filtered: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(record)) {
+      if (allowedFields.has(key)) {
+        filtered[key] = value;
+      } else if (!scalarFieldNames.has(key)) {
+        // Keep non-scalar fields that aren't in the model (e.g., _count, relation data)
+        // Only strip scalar fields that weren't selected
+        filtered[key] = value;
+      }
+    }
+    return filtered;
+  });
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+/**
+ * Convert a WhereUniqueInput (e.g. { id: 1 } or { email: "test@test.com" })
+ * to a WhereInput format suitable for the where builder.
+ *
+ * Handles compound unique keys: { userId_planId: { userId: 1, planId: 2 } }
+ * is expanded to { userId: 1, planId: 2 }.
+ */
+function convertUniqueToWhere(params: {
+  uniqueWhere: Record<string, unknown>;
+  modelMeta: ModelMeta;
+}): Record<string, unknown> {
+  const { uniqueWhere, modelMeta } = params;
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(uniqueWhere)) {
+    if (value === undefined) continue;
+
+    // Check if this is a scalar field — pass through directly
+    const isScalar = modelMeta.scalarFields.some((f) => f.name === key);
+    if (isScalar) {
+      result[key] = value;
+      continue;
+    }
+
+    // Check if this is a compound unique key (e.g. "userId_planId")
+    // These contain an object with the individual field values
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      const compound = value as Record<string, unknown>;
+      // Verify all sub-keys are scalar fields on this model
+      const allScalar = Object.keys(compound).every((k) =>
+        modelMeta.scalarFields.some((f) => f.name === k)
+      );
+      if (allScalar) {
+        // Expand compound key into individual field conditions
+        for (const [subKey, subValue] of Object.entries(compound)) {
+          result[subKey] = subValue;
+        }
+        continue;
+      }
+    }
+
+    // Pass through anything else (e.g. relation fields in select/include context)
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Auto-inject current timestamp for fields with @updatedAt.
+ */
+function injectUpdatedAt(params: {
+  data: Record<string, unknown>;
+  modelMeta: ModelMeta;
+}): void {
+  for (const sf of params.modelMeta.scalarFields) {
+    if (sf.isUpdatedAt && params.data[sf.name] === undefined) {
+      params.data[sf.name] = new Date();
+    }
+  }
+}
+
+/**
+ * Auto-inject generated values for fields with @default(uuid/cuid/nanoid/ulid)
+ * when the user hasn't provided a value.
+ *
+ * If a custom idGenerator is provided in options, it takes precedence.
+ * If the field has an idPrefix (from /// @vibeorm.idPrefix("...")), it is prepended.
+ */
+function injectAutoDefaults(params: {
+  data: Record<string, unknown>;
+  modelMeta: ModelMeta;
+  idGenerator?: (params: { model: string; field: string; defaultKind: string }) => string;
+}): void {
+  const { data, modelMeta, idGenerator } = params;
+  for (const sf of modelMeta.scalarFields) {
+    // Only inject for app-level defaults when the field is not provided
+    if (!sf.hasDefault || sf.hasDefault === true) continue;
+    if (data[sf.name] !== undefined) continue;
+
+    let value: string | undefined;
+
+    if (idGenerator) {
+      value = idGenerator({ model: modelMeta.name, field: sf.name, defaultKind: sf.hasDefault });
+    } else {
+      value = generateDefault({ kind: sf.hasDefault });
+    }
+
+    if (value !== undefined) {
+      // Prepend idPrefix if configured
+      if (sf.idPrefix) {
+        value = sf.idPrefix + value;
+      }
+      data[sf.name] = value;
+    }
+  }
+}
+
+/**
+ * Build parameterized SQL from a tagged template literal.
+ * Converts: sql`SELECT * FROM "User" WHERE id = ${1}`
+ * Into: { text: 'SELECT * FROM "User" WHERE id = $1', params: [1] }
+ */
+function buildTaggedTemplateSql(params: {
+  strings: TemplateStringsArray;
+  values: unknown[];
+}): { text: string; params: unknown[] } {
+  const { strings, values } = params;
+  let text = strings[0]!;
+  const sqlParams: unknown[] = [];
+
+  for (let i = 0; i < values.length; i++) {
+    sqlParams.push(values[i]);
+    text += `$${i + 1}${strings[i + 1] ?? ""}`;
+  }
+
+  return { text, params: sqlParams };
+}
+
+/**
+ * Parse a flat aggregate result row into the nested Prisma-style structure.
+ * Converts: { "_count__all": 5, "_avg__viewCount": 45.2, "authorId": 1 }
+ * Into: { _count: 5, _avg: { viewCount: 45.2 }, authorId: 1 }
+ */
+function parseAggregateResult(params: {
+  row: Record<string, unknown>;
+  args: Record<string, unknown>;
+}): Record<string, unknown> {
+  const { row, args } = params;
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(row)) {
+    if (key.startsWith("_") && key.includes("__")) {
+      // Aggregate column: "_count__all", "_avg__viewCount"
+      const [aggFn, field] = key.split("__") as [string, string];
+
+      if (aggFn === "_count") {
+        // _count: true returns a number, _count: { field: true } returns an object
+        const countArg = args._count;
+        if (countArg === true) {
+          result._count = Number(value ?? 0);
+        } else {
+          if (!result._count || typeof result._count !== "object") {
+            result._count = {};
+          }
+          if (field === "all") {
+            (result._count as Record<string, unknown>)._all = Number(value ?? 0);
+          } else {
+            (result._count as Record<string, unknown>)[field!] = Number(value ?? 0);
+          }
+        }
+      } else {
+        // _avg, _sum, _min, _max — always nested objects
+        if (!result[aggFn!]) {
+          result[aggFn!] = {};
+        }
+        let parsed: unknown = value;
+        if (value !== null && value !== undefined) {
+          const asNum = Number(value);
+          parsed = Number.isNaN(asNum) ? value : asNum;
+        }
+        (result[aggFn!] as Record<string, unknown>)[field!] = parsed;
+      }
+    } else {
+      // Regular field (for groupBy results)
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Resolve _count specification from include or select args.
+ * Returns the list of relation names to count, or null if _count not requested.
+ */
+function resolveCountSpec(params: { args: Record<string, unknown> }): string[] | null {
+  const { args } = params;
+  const include = args.include as Record<string, unknown> | undefined;
+  const select = args.select as Record<string, unknown> | undefined;
+
+  const countArg = include?._count ?? select?._count;
+  if (!countArg) return null;
+
+  if (countArg === true) {
+    // Count all list relations — will be resolved by loadRelationCounts
+    return ["__all__"];
+  }
+
+  if (typeof countArg === "object" && countArg !== null) {
+    const countObj = countArg as Record<string, unknown>;
+    const selectObj = countObj.select as Record<string, boolean> | undefined;
+    if (selectObj) {
+      return Object.entries(selectObj)
+        .filter(([_, enabled]) => enabled)
+        .map(([name]) => name);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Load relation counts and attach _count object to each record.
+ * Uses COUNT subqueries grouped by parent FK.
+ */
+async function loadRelationCounts(params: {
+  records: Record<string, unknown>[];
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  countSpec: string[];
+  executor: (params: { text: string; values: unknown[] }) => Promise<Record<string, unknown>[]>;
+}): Promise<void> {
+  const { records, modelMeta, allModelsMeta, countSpec, executor } = params;
+  const modelMap = getModelByNameMap({ allModelsMeta });
+  const parentPk = modelMeta.primaryKey[0];
+  if (!parentPk) return;
+
+  const parentIds = records.map((r) => r[parentPk]).filter((id) => id != null);
+  if (parentIds.length === 0) return;
+
+  // Resolve which relations to count
+  const listRelations = modelMeta.relationFields.filter((r) => r.isList);
+  const relationsToCount = countSpec.includes("__all__")
+    ? listRelations
+    : listRelations.filter((r) => countSpec.includes(r.name));
+
+  // Initialize _count on all records
+  for (const record of records) {
+    const countObj: Record<string, number> = {};
+    for (const rel of relationsToCount) {
+      countObj[rel.name] = 0;
+    }
+    record._count = countObj;
+  }
+
+  // Run all relation COUNT queries in parallel — each hits a different table
+  // so there are no data races on the parent records.
+  await Promise.all(
+    relationsToCount.map(async (rel) => {
+      const relatedModelMeta = modelMap.get(rel.relatedModel);
+      if (!relatedModelMeta) return;
+
+      // M:N relation: count via join table
+      if (rel.type === "manyToMany" && (rel as { joinTable?: string }).joinTable) {
+        const joinTableName = (rel as { joinTable?: string }).joinTable!;
+        const sorted = [modelMeta.name, relatedModelMeta.name].sort();
+        const parentIsA = modelMeta.name === sorted[0];
+        const parentCol = parentIsA ? "A" : "B";
+
+        const text = `SELECT "${joinTableName}"."${parentCol}" AS "__fk", COUNT(*) AS "__count" FROM "${joinTableName}" WHERE "${joinTableName}"."${parentCol}" = ANY($1) GROUP BY "${joinTableName}"."${parentCol}"`;
+        const result = await executor({ text, values: [new PgArray(parentIds)] });
+
+        const countMap = new Map<unknown, number>();
+        for (const row of result) {
+          countMap.set(row.__fk, Number(row.__count ?? 0));
+        }
+
+        for (const record of records) {
+          const pkValue = record[parentPk];
+          const cnt = countMap.get(pkValue) ?? 0;
+          (record._count as Record<string, number>)[rel.name] = cnt;
+        }
+        return;
+      }
+
+      // Find the FK column on the related model (with relationName disambiguation)
+      const reverseRel = relatedModelMeta.relationFields.find(
+        (r) => r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0 &&
+          (!rel.relationName || r.relationName === rel.relationName)
+      );
+      if (!reverseRel) return;
+
+      const fkField = reverseRel.fields[0]!;
+      const relatedSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
+      const fkScalar = relatedSfMap.get(fkField);
+      const fkDbName = fkScalar?.dbName ?? fkField;
+      const relatedTable = `"${relatedModelMeta.dbName}"`;
+
+      // Build: SELECT "fk" AS "__fk", COUNT(*) AS "__count" FROM "related" WHERE "fk" = ANY($1) GROUP BY "fk"
+      const text = `SELECT ${relatedTable}."${fkDbName}" AS "__fk", COUNT(*) AS "__count" FROM ${relatedTable} WHERE ${relatedTable}."${fkDbName}" = ANY($1) GROUP BY ${relatedTable}."${fkDbName}"`;
+      const result = await executor({ text, values: [new PgArray(parentIds)] });
+
+      // Map counts back to parent records
+      const countMap = new Map<unknown, number>();
+      for (const row of result) {
+        countMap.set(row.__fk, Number(row.__count ?? 0));
+      }
+
+      for (const record of records) {
+        const pkValue = record[parentPk];
+        const cnt = countMap.get(pkValue) ?? 0;
+        (record._count as Record<string, number>)[rel.name] = cnt;
+      }
+    })
+  );
+}
+
+type NestedOp = {
+  relationField: ModelMeta["relationFields"][number];
+  ops: Record<string, unknown>;
+};
+
+/**
+ * Separate scalar data from nested relation operations in update data.
+ */
+function separateNestedOps(params: {
+  data: Record<string, unknown>;
+  modelMeta: ModelMeta;
+}): { scalarData: Record<string, unknown>; nestedOps: NestedOp[] } {
+  const { data, modelMeta } = params;
+  const scalarData: Record<string, unknown> = {};
+  const nestedOps: NestedOp[] = [];
+
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined) continue;
+
+    const relationField = modelMeta.relationFields.find((f) => f.name === key);
+    if (relationField && typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date)) {
+      nestedOps.push({ relationField, ops: value as Record<string, unknown> });
+    } else {
+      scalarData[key] = value;
+    }
+  }
+
+  return { scalarData, nestedOps };
+}
+
+/**
+ * Process nested relation operations for an update.
+ * Handles: connect, disconnect, create, delete, set, connectOrCreate, update, upsert, updateMany, deleteMany
+ */
+async function processNestedUpdateOps(params: {
+  parentRecord: Record<string, unknown>;
+  nestedOps: NestedOp[];
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  executor: (params: { text: string; values: unknown[] }) => Promise<Record<string, unknown>[]>;
+}): Promise<void> {
+  const { parentRecord, nestedOps, modelMeta, allModelsMeta, executor } = params;
+  const modelMap = getModelByNameMap({ allModelsMeta });
+
+  for (const { relationField, ops } of nestedOps) {
+    const relatedModelMeta = modelMap.get(relationField.relatedModel);
+    if (!relatedModelMeta) continue;
+
+    const parentPk = modelMeta.primaryKey[0];
+    if (!parentPk) continue;
+    const parentId = parentRecord[parentPk];
+
+    // To-one relation where parent holds FK (e.g., Post.author / Post.authorId)
+    if (!relationField.isList && relationField.isForeignKey && relationField.fields.length > 0) {
+      const fkField = relationField.fields[0]!;
+      const refField = relationField.references[0]!;
+
+      if (ops.connect) {
+        const connectData = ops.connect as Record<string, unknown>;
+        const fkValue = connectData[refField];
+        if (fkValue !== undefined) {
+          const query = buildUpdateQuery({
+            modelMeta,
+            allModelsMeta,
+            where: { [parentPk]: parentId },
+            data: { [fkField]: fkValue },
+          });
+          await executor(query);
+        }
+      }
+
+      if (ops.disconnect === true) {
+        const query = buildUpdateQuery({
+          modelMeta,
+          allModelsMeta,
+          where: { [parentPk]: parentId },
+          data: { [fkField]: null },
+        });
+        await executor(query);
+      }
+
+      if (ops.delete === true) {
+        // First read FK, then delete the related record, then null the FK
+        const fkValue = parentRecord[fkField];
+        if (fkValue != null) {
+          // Null out FK first
+          const nullQuery = buildUpdateQuery({
+            modelMeta,
+            allModelsMeta,
+            where: { [parentPk]: parentId },
+            data: { [fkField]: null },
+          });
+          await executor(nullQuery);
+          // Then delete the related record
+          const delQuery = buildDeleteQuery({
+            modelMeta: relatedModelMeta,
+            allModelsMeta,
+            where: { [refField]: fkValue },
+          });
+          await executor(delQuery);
+        }
+      }
+
+      if (ops.create) {
+        const createData = ops.create as Record<string, unknown>;
+        const insertQuery = buildInsertQuery({ modelMeta: relatedModelMeta, data: createData });
+        const insertedRows = await executor(insertQuery);
+        const inserted = insertedRows[0];
+        if (inserted) {
+          const relatedPk = relatedModelMeta.primaryKey[0]!;
+          const query = buildUpdateQuery({
+            modelMeta,
+            allModelsMeta,
+            where: { [parentPk]: parentId },
+            data: { [fkField]: inserted[relatedPk] },
+          });
+          await executor(query);
+        }
+      }
+
+      // connectOrCreate: find existing or create, then set FK on parent
+      if (ops.connectOrCreate) {
+        const { where: corWhere, create: corCreate } = ops.connectOrCreate as { where: Record<string, unknown>; create: Record<string, unknown> };
+        const findQuery = buildSelectQuery({ modelMeta: relatedModelMeta, allModelsMeta, args: { where: corWhere, take: 1 } });
+        const existing = await executor(findQuery);
+        if (existing.length > 0) {
+          const fkValue = existing[0]![refField];
+          if (fkValue !== undefined) {
+            const query = buildUpdateQuery({ modelMeta, allModelsMeta, where: { [parentPk]: parentId }, data: { [fkField]: fkValue } });
+            await executor(query);
+          }
+        } else {
+          const insertQuery = buildInsertQuery({ modelMeta: relatedModelMeta, data: corCreate });
+          const insertedRows = await executor(insertQuery);
+          const inserted = insertedRows[0];
+          if (inserted) {
+            const relatedPk = relatedModelMeta.primaryKey[0]!;
+            const query = buildUpdateQuery({ modelMeta, allModelsMeta, where: { [parentPk]: parentId }, data: { [fkField]: inserted[relatedPk] } });
+            await executor(query);
+          }
+        }
+      }
+
+      // update (nested): update the currently connected related record
+      if (ops.update) {
+        const updateData = ops.update as Record<string, unknown>;
+        const fkValue = parentRecord[fkField];
+        if (fkValue != null) {
+          const query = buildUpdateQuery({ modelMeta: relatedModelMeta, allModelsMeta, where: { [refField]: fkValue }, data: updateData });
+          await executor(query);
+        }
+      }
+
+      // upsert: update related if connected, create if not
+      if (ops.upsert) {
+        const { create: upsCreate, update: upsUpdate } = ops.upsert as { create: Record<string, unknown>; update: Record<string, unknown> };
+        const fkValue = parentRecord[fkField];
+        if (fkValue != null) {
+          // Related record exists — update it
+          const query = buildUpdateQuery({ modelMeta: relatedModelMeta, allModelsMeta, where: { [refField]: fkValue }, data: upsUpdate });
+          await executor(query);
+        } else {
+          // No related record — create one and set FK on parent
+          const insertQuery = buildInsertQuery({ modelMeta: relatedModelMeta, data: upsCreate });
+          const insertedRows = await executor(insertQuery);
+          const inserted = insertedRows[0];
+          if (inserted) {
+            const relatedPk = relatedModelMeta.primaryKey[0]!;
+            const query = buildUpdateQuery({ modelMeta, allModelsMeta, where: { [parentPk]: parentId }, data: { [fkField]: inserted[relatedPk] } });
+            await executor(query);
+          }
+        }
+      }
+
+      continue;
+    }
+
+    // To-one relation where related holds FK (e.g., User.profile where Profile.userId → User.id)
+    if (!relationField.isList && !relationField.isForeignKey) {
+      const reverseRel = relatedModelMeta.relationFields.find(
+        (r) => r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0
+      );
+      if (!reverseRel) continue;
+      const reverseFk = reverseRel.fields[0]!;
+      const reverseRef = reverseRel.references[0]!;
+      const parentRefValue = parentRecord[reverseRef];
+
+      if (ops.connect) {
+        const connectData = ops.connect as Record<string, unknown>;
+        const relatedPk = relatedModelMeta.primaryKey[0]!;
+        const relatedId = connectData[relatedPk];
+        if (relatedId !== undefined) {
+          const query = buildUpdateQuery({
+            modelMeta: relatedModelMeta,
+            allModelsMeta,
+            where: { [relatedPk]: relatedId },
+            data: { [reverseFk]: parentRefValue },
+          });
+          await executor(query);
+        }
+      }
+
+      if (ops.disconnect === true) {
+        const query = buildUpdateManyQuery({
+          modelMeta: relatedModelMeta,
+          allModelsMeta,
+          where: { [reverseFk]: parentRefValue },
+          data: { [reverseFk]: null },
+        });
+        await executor(query);
+      }
+
+      if (ops.delete === true) {
+        const query = buildDeleteQuery({
+          modelMeta: relatedModelMeta,
+          allModelsMeta,
+          where: { [reverseFk]: parentRefValue },
+        });
+        await executor(query);
+      }
+
+      if (ops.create) {
+        const createData = ops.create as Record<string, unknown>;
+        (createData as Record<string, unknown>)[reverseFk] = parentRefValue;
+        const query = buildInsertQuery({ modelMeta: relatedModelMeta, data: createData });
+        await executor(query);
+      }
+
+      // connectOrCreate: find existing or create, then set FK on related record
+      if (ops.connectOrCreate) {
+        const { where: corWhere, create: corCreate } = ops.connectOrCreate as { where: Record<string, unknown>; create: Record<string, unknown> };
+        const findQuery = buildSelectQuery({ modelMeta: relatedModelMeta, allModelsMeta, args: { where: corWhere, take: 1 } });
+        const existing = await executor(findQuery);
+        if (existing.length > 0) {
+          const relatedPk = relatedModelMeta.primaryKey[0]!;
+          const relatedId = existing[0]![relatedPk];
+          if (relatedId !== undefined) {
+            const query = buildUpdateQuery({ modelMeta: relatedModelMeta, allModelsMeta, where: { [relatedPk]: relatedId }, data: { [reverseFk]: parentRefValue } });
+            await executor(query);
+          }
+        } else {
+          (corCreate as Record<string, unknown>)[reverseFk] = parentRefValue;
+          const insertQuery = buildInsertQuery({ modelMeta: relatedModelMeta, data: corCreate });
+          await executor(insertQuery);
+        }
+      }
+
+      // update (nested): update the related record that points to this parent
+      if (ops.update) {
+        const updateData = ops.update as Record<string, unknown>;
+        const query = buildUpdateQuery({ modelMeta: relatedModelMeta, allModelsMeta, where: { [reverseFk]: parentRefValue }, data: updateData });
+        await executor(query);
+      }
+
+      // upsert: update related if exists, create if not
+      if (ops.upsert) {
+        const { create: upsCreate, update: upsUpdate } = ops.upsert as { create: Record<string, unknown>; update: Record<string, unknown> };
+        // Check if related record exists
+        const findQuery = buildSelectQuery({ modelMeta: relatedModelMeta, allModelsMeta, args: { where: { [reverseFk]: parentRefValue }, take: 1 } });
+        const existing = await executor(findQuery);
+        if (existing.length > 0) {
+          const query = buildUpdateQuery({ modelMeta: relatedModelMeta, allModelsMeta, where: { [reverseFk]: parentRefValue }, data: upsUpdate });
+          await executor(query);
+        } else {
+          (upsCreate as Record<string, unknown>)[reverseFk] = parentRefValue;
+          const insertQuery = buildInsertQuery({ modelMeta: relatedModelMeta, data: upsCreate });
+          await executor(insertQuery);
+        }
+      }
+
+      continue;
+    }
+
+    // To-many relation (e.g., User.posts)
+    if (relationField.isList) {
+      const reverseRel = relatedModelMeta.relationFields.find(
+        (r) => r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0
+      );
+      if (!reverseRel) continue;
+      const reverseFk = reverseRel.fields[0]!;
+      const reverseRef = reverseRel.references[0]!;
+      const parentRefValue = parentRecord[reverseRef];
+      const relatedPk = relatedModelMeta.primaryKey[0]!;
+
+      // set: replace all — disconnect all, then connect the specified ones
+      if (ops.set) {
+        const setItems = ops.set as Record<string, unknown>[];
+        // Disconnect all existing
+        const disconnectAllQuery = buildUpdateManyQuery({
+          modelMeta: relatedModelMeta,
+          allModelsMeta,
+          where: { [reverseFk]: parentRefValue },
+          data: { [reverseFk]: null },
+        });
+        await executor(disconnectAllQuery);
+        // Batch connect: single UPDATE ... SET fk = $1 WHERE pk = ANY($2)
+        const setIds = setItems.map((item) => item[relatedPk]).filter((id) => id !== undefined);
+        if (setIds.length > 0) {
+          const query = buildUpdateManyQuery({
+            modelMeta: relatedModelMeta,
+            allModelsMeta,
+            where: { [relatedPk]: { in: setIds } },
+            data: { [reverseFk]: parentRefValue },
+          });
+          await executor(query);
+        }
+      }
+
+      // Batch connect: single UPDATE ... SET fk = $1 WHERE pk = ANY($2)
+      if (ops.connect) {
+        const connectItems = Array.isArray(ops.connect) ? ops.connect : [ops.connect];
+        const ids = (connectItems as Record<string, unknown>[]).map((item) => item[relatedPk]).filter((id) => id !== undefined);
+        if (ids.length > 0) {
+          const query = buildUpdateManyQuery({
+            modelMeta: relatedModelMeta,
+            allModelsMeta,
+            where: { [relatedPk]: { in: ids } },
+            data: { [reverseFk]: parentRefValue },
+          });
+          await executor(query);
+        }
+      }
+
+      // Batch disconnect: single UPDATE ... SET fk = NULL WHERE pk = ANY($1)
+      if (ops.disconnect) {
+        const disconnectItems = Array.isArray(ops.disconnect) ? ops.disconnect : [ops.disconnect];
+        const ids = (disconnectItems as Record<string, unknown>[]).map((item) => item[relatedPk]).filter((id) => id !== undefined);
+        if (ids.length > 0) {
+          const query = buildUpdateManyQuery({
+            modelMeta: relatedModelMeta,
+            allModelsMeta,
+            where: { [relatedPk]: { in: ids } },
+            data: { [reverseFk]: null },
+          });
+          await executor(query);
+        }
+      }
+
+      // Batch delete: single DELETE ... WHERE pk = ANY($1)
+      if (ops.delete) {
+        const deleteItems = Array.isArray(ops.delete) ? ops.delete : [ops.delete];
+        const ids = (deleteItems as Record<string, unknown>[]).map((item) => item[relatedPk]).filter((id) => id !== undefined);
+        if (ids.length > 0) {
+          const query = buildDeleteQuery({
+            modelMeta: relatedModelMeta,
+            allModelsMeta,
+            where: { [relatedPk]: { in: ids } },
+          });
+          await executor(query);
+        }
+      }
+
+      // Batch create: single multi-row INSERT
+      if (ops.create) {
+        const createItems = Array.isArray(ops.create) ? ops.create : [ops.create];
+        const dataArray = (createItems as Record<string, unknown>[]).map((createData) => {
+          (createData as Record<string, unknown>)[reverseFk] = parentRefValue;
+          return createData;
+        });
+        if (dataArray.length === 1) {
+          const query = buildInsertQuery({ modelMeta: relatedModelMeta, data: dataArray[0]! });
+          await executor(query);
+        } else if (dataArray.length > 1) {
+          const query = buildInsertManyQuery({ modelMeta: relatedModelMeta, data: dataArray, returning: false });
+          await executor(query);
+        }
+      }
+
+      // connectOrCreate: find existing or create, then set FK on related record
+      if (ops.connectOrCreate) {
+        const items = Array.isArray(ops.connectOrCreate) ? ops.connectOrCreate : [ops.connectOrCreate];
+        for (const item of items as { where: Record<string, unknown>; create: Record<string, unknown> }[]) {
+          const findQuery = buildSelectQuery({ modelMeta: relatedModelMeta, allModelsMeta, args: { where: item.where, take: 1 } });
+          const existing = await executor(findQuery);
+          if (existing.length > 0) {
+            const relatedId = existing[0]![relatedPk];
+            if (relatedId !== undefined) {
+              const query = buildUpdateQuery({ modelMeta: relatedModelMeta, allModelsMeta, where: { [relatedPk]: relatedId }, data: { [reverseFk]: parentRefValue } });
+              await executor(query);
+            }
+          } else {
+            (item.create as Record<string, unknown>)[reverseFk] = parentRefValue;
+            const insertQuery = buildInsertQuery({ modelMeta: relatedModelMeta, data: item.create });
+            await executor(insertQuery);
+          }
+        }
+      }
+
+      // update (nested): update related records by where + data
+      if (ops.update) {
+        const items = Array.isArray(ops.update) ? ops.update : [ops.update];
+        for (const item of items as { where: Record<string, unknown>; data: Record<string, unknown> }[]) {
+          const query = buildUpdateQuery({ modelMeta: relatedModelMeta, allModelsMeta, where: { ...item.where, [reverseFk]: parentRefValue }, data: item.data });
+          await executor(query);
+        }
+      }
+
+      // upsert: upsert related records by where + create/update
+      if (ops.upsert) {
+        const items = Array.isArray(ops.upsert) ? ops.upsert : [ops.upsert];
+        for (const item of items as { where: Record<string, unknown>; create: Record<string, unknown>; update: Record<string, unknown> }[]) {
+          const findQuery = buildSelectQuery({ modelMeta: relatedModelMeta, allModelsMeta, args: { where: { ...item.where, [reverseFk]: parentRefValue }, take: 1 } });
+          const existing = await executor(findQuery);
+          if (existing.length > 0) {
+            const query = buildUpdateQuery({ modelMeta: relatedModelMeta, allModelsMeta, where: { ...item.where, [reverseFk]: parentRefValue }, data: item.update });
+            await executor(query);
+          } else {
+            (item.create as Record<string, unknown>)[reverseFk] = parentRefValue;
+            const insertQuery = buildInsertQuery({ modelMeta: relatedModelMeta, data: item.create });
+            await executor(insertQuery);
+          }
+        }
+      }
+
+      // updateMany: update multiple related records by filter
+      if (ops.updateMany) {
+        const items = Array.isArray(ops.updateMany) ? ops.updateMany : [ops.updateMany];
+        for (const item of items as { where: Record<string, unknown>; data: Record<string, unknown> }[]) {
+          const query = buildUpdateManyQuery({ modelMeta: relatedModelMeta, allModelsMeta, where: { ...item.where, [reverseFk]: parentRefValue }, data: item.data });
+          await executor(query);
+        }
+      }
+
+      // deleteMany: delete multiple related records by filter
+      if (ops.deleteMany) {
+        const items = Array.isArray(ops.deleteMany) ? ops.deleteMany : [ops.deleteMany];
+        for (const item of items as Record<string, unknown>[]) {
+          const query = buildDeleteQuery({ modelMeta: relatedModelMeta, allModelsMeta, where: { ...item, [reverseFk]: parentRefValue } });
+          await executor(query);
+        }
+      }
+    }
+  }
+}
+
+type DeferredCreate = {
+  relatedModelMeta: ModelMeta;
+  fkField: string;
+  parentRefField: string;
+  createData: unknown;
+};
+
+/**
+ * Process nested create/connect operations in the data object.
+ * Extracts relation fields and handles them separately.
+ *
+ * Returns:
+ * - processedData: scalar data ready for INSERT (with FK values resolved from connect/create)
+ * - deferredCreates: nested creates where the related model holds the FK (must run after parent INSERT)
+ */
+async function processNestedCreates(params: {
+  data: Record<string, unknown>;
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  executor: (params: {
+    text: string;
+    values: unknown[];
+  }) => Promise<Record<string, unknown>[]>;
+}): Promise<{ processedData: Record<string, unknown>; deferredCreates: DeferredCreate[] }> {
+  const { data, modelMeta, allModelsMeta, executor } = params;
+  const processedData: Record<string, unknown> = {};
+  const deferredCreates: DeferredCreate[] = [];
+  const modelMap = getModelByNameMap({ allModelsMeta });
+
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined) continue;
+
+    // Check if this is a relation field
+    const relationField = modelMeta.relationFields.find(
+      (f) => f.name === key
+    );
+
+    if (!relationField) {
+      // Scalar field — keep as is
+      processedData[key] = value;
+      continue;
+    }
+
+    // Handle nested relation operations
+    if (typeof value === "object" && value !== null) {
+      const ops = value as Record<string, unknown>;
+
+      // Case 1: Parent holds the FK (e.g., Post.author where Post has authorId)
+      if (relationField.isForeignKey && relationField.fields.length > 0) {
+        const fkField = relationField.fields[0]!;
+        const refField = relationField.references[0]!;
+
+        if (ops.connect) {
+          // Connect: set the FK value from the connected record's unique fields
+          const connectData = ops.connect as Record<string, unknown>;
+          if (connectData[refField] !== undefined) {
+            processedData[fkField] = connectData[refField];
+          }
+        }
+
+        if (ops.create) {
+          // Create: insert the related record first, then use its PK as FK value
+          const relatedMeta = modelMap.get(relationField.relatedModel);
+          if (relatedMeta) {
+            const createData = ops.create as Record<string, unknown>;
+            const insertQuery = buildInsertQuery({ modelMeta: relatedMeta, data: createData });
+            const insertedRows = await executor(insertQuery);
+            const inserted = insertedRows[0];
+            if (inserted) {
+              processedData[fkField] = inserted[refField];
+            }
+          }
+        }
+      }
+      // Case 2: Related model holds the FK (e.g., User.posts where Post has userId)
+      else if (!relationField.isForeignKey) {
+        const relatedMeta = modelMap.get(relationField.relatedModel);
+        if (!relatedMeta) continue;
+
+        const reverseRel = relatedMeta.relationFields.find(
+          (r) => r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0
+        );
+        if (!reverseRel) continue;
+
+        const reverseFk = reverseRel.fields[0]!;
+        const reverseRef = reverseRel.references[0]!;
+
+        if (ops.connect) {
+          // For connect on the non-FK side, we need deferred processing
+          // (need parent PK first to set on the related record)
+          // This is uncommon for CREATE — usually you'd connect from the FK side
+        }
+
+        if (ops.create) {
+          // Defer: create after parent insert so we have parent's PK
+          deferredCreates.push({
+            relatedModelMeta: relatedMeta,
+            fkField: reverseFk,
+            parentRefField: reverseRef,
+            createData: ops.create,
+          });
+        }
+      }
+    }
+  }
+
+  return { processedData, deferredCreates };
+}