postgresdk 0.18.29 → 0.19.0

package/dist/cli.js

@@ -492,6 +492,14 @@ var require_config = __commonJS(() => {
 import { mkdir, writeFile, readFile, readdir, unlink } from "fs/promises";
 import { dirname, join } from "path";
 import { existsSync } from "fs";
+function isVectorType(pgType) {
+  const t = pgType.toLowerCase();
+  return t === "vector" || t === "halfvec" || t === "sparsevec" || t === "bit";
+}
+function isJsonbType(pgType) {
+  const t = pgType.toLowerCase();
+  return t === "json" || t === "jsonb";
+}
 async function writeFilesIfChanged(files) {
   let written = 0;
   let unchanged = 0;
@@ -890,9 +898,10 @@ function generateResourceWithSDK(table, model, graph, config) {
   const hasSinglePK = table.pk.length === 1;
   const pkField = hasSinglePK ? table.pk[0] : "id";
   const enums = model.enums || {};
-  const overrides = config?.softDeleteColumnOverrides;
-  const resolvedSoftDeleteCol = overrides && tableName in overrides ? overrides[tableName] ?? null : config?.softDeleteColumn ?? null;
+  const overrides = config?.delete?.softDeleteColumnOverrides;
+  const resolvedSoftDeleteCol = overrides && tableName in overrides ? overrides[tableName] ?? null : config?.delete?.softDeleteColumn ?? null;
   const softDeleteCol = resolvedSoftDeleteCol && table.columns.some((c) => c.name === resolvedSoftDeleteCol) ? resolvedSoftDeleteCol : null;
+  const exposeHardDelete = config?.delete?.exposeHardDelete ?? true;
   const sdkMethods = [];
   const endpoints = [];
   sdkMethods.push({
@@ -968,16 +977,47 @@ const withDeleted = await sdk.${tableName}.getByPk('id', { includeSoftDeleted: t
   }
   if (hasSinglePK) {
     sdkMethods.push({
-      name: "delete",
-      signature: `delete(${pkField}: string): Promise<${Type}>`,
-      description: `Delete a ${tableName}`,
-      example: `const deleted = await sdk.${tableName}.delete('id');`,
-      correspondsTo: `DELETE ${basePath}/:${pkField}`
+      name: "upsert",
+      signature: `upsert(args: { where: Update${Type}; create: Insert${Type}; update: Update${Type} }): Promise<${Type}>`,
+      description: `Insert or update a ${tableName} based on a conflict target. The 'where' keys define the unique conflict columns (must be a unique constraint). 'create' is used if no conflict; 'update' is applied if a conflict occurs.`,
+      example: `const result = await sdk.${tableName}.upsert({
+  where: { ${pkField}: 'some-id' },
+  create: { ${generateExampleFields(table, "create")} },
+  update: { ${generateExampleFields(table, "update")} },
+});`,
+      correspondsTo: `POST ${basePath}/upsert`
+    });
+    endpoints.push({
+      method: "POST",
+      path: `${basePath}/upsert`,
+      description: `Upsert ${tableName} — insert if no conflict on 'where' columns, update otherwise`,
+      requestBody: `{ where: Update${Type}; create: Insert${Type}; update: Update${Type} }`,
+      responseBody: `${Type}`
     });
+  }
+  if (hasSinglePK) {
+    if (softDeleteCol) {
+      sdkMethods.push({
+        name: "softDelete",
+        signature: `softDelete(${pkField}: string): Promise<${Type}>`,
+        description: `Soft-delete a ${tableName} (sets ${softDeleteCol})`,
+        example: `const deleted = await sdk.${tableName}.softDelete('id');`,
+        correspondsTo: `DELETE ${basePath}/:${pkField}`
+      });
+    }
+    if (!softDeleteCol || exposeHardDelete) {
+      sdkMethods.push({
+        name: "hardDelete",
+        signature: `hardDelete(${pkField}: string): Promise<${Type}>`,
+        description: `Permanently delete a ${tableName}`,
+        example: `const deleted = await sdk.${tableName}.hardDelete('id');`,
+        correspondsTo: softDeleteCol ? `DELETE ${basePath}/:${pkField}?hard=true` : `DELETE ${basePath}/:${pkField}`
+      });
+    }
     endpoints.push({
       method: "DELETE",
       path: `${basePath}/:${pkField}`,
-      description: `Delete ${tableName}`,
+      description: softDeleteCol ? `Delete ${tableName} (soft-delete by default${exposeHardDelete ? "; add ?hard=true for permanent deletion" : ""})` : `Delete ${tableName}`,
       responseBody: `${Type}`
     });
   }
@@ -1475,7 +1515,7 @@ function extractConfigFields(configContent) {
   if (connectionMatch) {
     fields.push({
       key: "connectionString",
-      value: connectionMatch[1]?.trim(),
+      value: connectionMatch[1]?.trim().replace(/\s*\/\/.*$/, ""),
       description: "PostgreSQL connection string",
       isRequired: true,
       isCommented: false
@@ -1495,7 +1535,7 @@ function extractConfigFields(configContent) {
   const outClientMatch = configContent.match(/^\s*(\/\/)?\s*outClient:\s*"(.+)"/m);
   if (outDirMatch) {
     let value = outDirMatch[2]?.trim() || "";
-    value = value.replace(/,\s*$/, "");
+    value = value.replace(/\s*\/\/.*$/, "").replace(/,\s*$/, "");
     fields.push({
       key: "outDir",
       value,
@@ -1513,13 +1553,13 @@ function extractConfigFields(configContent) {
       isCommented
     });
   }
-  const softDeleteMatch = configContent.match(/^\s*(\/\/)?\s*softDeleteColumn:\s*(.+),?$/m);
-  if (softDeleteMatch) {
+  const deleteBlock = extractComplexBlock(configContent, "delete");
+  if (deleteBlock) {
     fields.push({
-      key: "softDeleteColumn",
-      value: softDeleteMatch[2]?.trim().replace(/,$/, "").replace(/["']/g, ""),
-      description: "Column name for soft deletes",
-      isCommented: !!softDeleteMatch[1]
+      key: "delete",
+      value: deleteBlock.content,
+      description: "Delete configuration (soft/hard delete behavior)",
+      isCommented: deleteBlock.isCommented
     });
   }
   const depthMatch = configContent.match(/^\s*(\/\/)?\s*(includeMethodsDepth|includeDepthLimit):\s*(\d+)/m);
@@ -1594,11 +1634,11 @@ function extractConfigFields(configContent) {
       isCommented: pullBlock.isCommented
     });
   }
-  const pullTokenMatch = configContent.match(/^\s*(\/\/)?\s*pullToken:\s*(.+),?$/m);
+  const pullTokenMatch = configContent.match(/^[ \t]{0,3}(\/\/)?\s*pullToken:\s*(.+),?$/m);
   if (pullTokenMatch) {
     fields.push({
       key: "pullToken",
-      value: pullTokenMatch[2]?.trim().replace(/,$/, ""),
+      value: pullTokenMatch[2]?.trim().replace(/\s*\/\/.*$/, "").replace(/,$/, ""),
       description: "Token for protecting /_psdk/* endpoints",
       isCommented: !!pullTokenMatch[1]
     });
@@ -1701,12 +1741,12 @@ export default {
   // ========== ADVANCED OPTIONS ==========
   
   /**
-   * Column name for soft deletes. When set, DELETE operations will update
-   * this column instead of removing rows.
-   * @default null (hard deletes)
-   * @example "deleted_at"
+   * Delete configuration (soft/hard delete behavior).
+   * When softDeleteColumn is set, DELETE operations update that column instead of removing rows.
+   * Set exposeHardDelete: false to prevent permanent deletion via the API.
+   * @default undefined (hard deletes only)
    */
-  ${getFieldLine("softDeleteColumn", existingFields, mergeStrategy, "null", userChoices)}
+  ${getComplexBlockLine("delete", existingFields, mergeStrategy, userChoices)}
 
   /**
    * How to type numeric columns in TypeScript
@@ -1795,6 +1835,12 @@ export default {
 `;
   return template;
 }
+function wrapValue(value) {
+  if (typeof value === "string" && !value.startsWith('"') && !value.startsWith("{") && !value.startsWith("[")) {
+    return `"${value}"`;
+  }
+  return String(value);
+}
 function getFieldValue(key, existingFields, mergeStrategy, userChoices) {
   const existing = existingFields.find((f) => f.key === key);
   if (mergeStrategy === "keep-existing" && existing && !existing.isCommented) {
@@ -1821,31 +1867,29 @@ function getFieldLine(key, existingFields, mergeStrategy, defaultValue, userChoi
   const shouldUseExisting = mergeStrategy === "keep-existing" && existing && !existing.isCommented || mergeStrategy === "interactive" && userChoices?.get(key) === "keep" && existing && !existing.isCommented;
   const shouldUseNew = mergeStrategy === "use-defaults" || mergeStrategy === "interactive" && userChoices?.get(key) === "new";
   if (shouldUseExisting && existing) {
-    let value = existing.value;
-    if (typeof value === "string" && !value.startsWith('"') && !value.startsWith("{") && !value.startsWith("[")) {
-      value = `"${value}"`;
-    }
-    return `${key}: ${value},`;
+    return `${key}: ${wrapValue(existing.value)},`;
   }
   if (shouldUseNew) {
     return `${key}: ${defaultValue},`;
   }
-  return `// ${key}: ${defaultValue},`;
+  return `// ${key}: ${existing ? wrapValue(existing.value) : defaultValue},`;
 }
 function getComplexBlockLine(key, existingFields, mergeStrategy, userChoices) {
   const existing = existingFields.find((f) => f.key === key);
   const shouldUseExisting = mergeStrategy === "keep-existing" && existing && !existing.isCommented || mergeStrategy === "interactive" && userChoices?.get(key) === "keep" && existing && !existing.isCommented;
-  const shouldUseNew = mergeStrategy === "use-defaults" || mergeStrategy === "interactive" && userChoices?.get(key) === "new";
   if (shouldUseExisting && existing) {
     return `${key}: ${existing.value},`;
   }
-  if (shouldUseNew) {
-    return getDefaultComplexBlock(key);
-  }
   return getDefaultComplexBlock(key);
 }
 function getDefaultComplexBlock(key) {
   switch (key) {
+    case "delete":
+      return `// delete: {
+  //   softDeleteColumn: "deleted_at",
+  //   exposeHardDelete: true,       // default: true
+  //   // softDeleteColumnOverrides: { audit_logs: null }
+  // },`;
     case "tests":
       return `// tests: {
   //   generate: true,
@@ -1973,30 +2017,6 @@ async function initCommand(args) {
         }
         userChoices.set(field.key, choice);
       }
-      const newOptions = [
-        { key: "tests", description: "Enable test generation" },
-        { key: "auth", description: "Add authentication" },
-        { key: "pullToken", description: "Add SDK endpoint protection" },
-        { key: "pull", description: "Configure SDK distribution" }
-      ];
-      const existingKeys = new Set(existingFields.map((f) => f.key));
-      const missingOptions = newOptions.filter((opt) => !existingKeys.has(opt.key));
-      if (missingOptions.length > 0) {
-        console.log(`
-\uD83D\uDCE6 New configuration options available:
-`);
-        for (const option of missingOptions) {
-          const { addOption } = await prompts2({
-            type: "confirm",
-            name: "addOption",
-            message: `Add ${option.description} configuration? (commented out by default)`,
-            initial: false
-          });
-          if (addOption) {
-            userChoices.set(option.key, "add-commented");
-          }
-        }
-      }
     }
     const backupPath = configPath + ".backup." + Date.now();
     copyFileSync(configPath, backupPath);
@@ -2137,13 +2157,14 @@ export default {
   // ========== ADVANCED OPTIONS ==========
 
   /**
-   * Column name for soft deletes. When set, DELETE operations will update
-   * this column instead of removing rows.
-   *
-   * Default: null (hard deletes)
-   * Example: "deleted_at"
+   * Delete configuration (soft/hard delete behavior).
+   * When softDeleteColumn is set, DELETE operations update that column instead of removing rows.
+   * Set exposeHardDelete: false to prevent permanent deletion via the API.
    */
-  // softDeleteColumn: null,
+  // delete: {
+  //   softDeleteColumn: "deleted_at",
+  //   exposeHardDelete: true,
+  // },
 
   /**
    * How to type numeric columns in TypeScript
@@ -2712,7 +2733,7 @@ function emitIncludeResolver(graph, useJsExtensions) {
     const edges = graph[table] || {};
     const edgeEntries = Object.entries(edges);
     if (edgeEntries.length === 0) {
-      out += `export type ${Type}WithIncludes<TInclude extends ${Type}IncludeSpec> = Select${Type};
+      out += `export type ${Type}WithIncludes<_TInclude extends ${Type}IncludeSpec> = Select${Type};
 
 `;
       continue;
@@ -2858,6 +2879,18 @@ ${insertFields}
 });
 
 export const Update${Type}Schema = Insert${Type}Schema.partial();
+
+export const Upsert${Type}Schema = z.object({
+  where: Update${Type}Schema.refine(
+    (d) => Object.keys(d).length > 0,
+    { message: "where must specify at least one column" }
+  ),
+  create: Insert${Type}Schema,
+  update: Update${Type}Schema.refine(
+    (d) => Object.keys(d).length > 0,
+    { message: "update must specify at least one column" }
+  ),
+});
 `;
 }
 
@@ -2951,13 +2984,6 @@ export interface PaginatedResponse<T> {
 
 // src/emit-routes-hono.ts
 init_utils();
-function isVectorType(pgType) {
-  const t = pgType.toLowerCase();
-  return t === "vector" || t === "halfvec" || t === "sparsevec" || t === "bit";
-}
-function isJsonbType(pgType) {
-  return pgType.toLowerCase() === "json" || pgType.toLowerCase() === "jsonb";
-}
 function emitHonoRoutes(table, _graph, opts) {
   const fileTableName = table.name;
   const Type = pascal(table.name);
@@ -2971,6 +2997,7 @@ function emitHonoRoutes(table, _graph, opts) {
   const hasCompositePk = safePkCols.length > 1;
   const pkPath = hasCompositePk ? safePkCols.map((c) => `:${c}`).join("/") : `:${safePkCols[0]}`;
   const softDel = opts.softDeleteColumn && table.columns.some((c) => c.name === opts.softDeleteColumn) ? opts.softDeleteColumn : null;
+  const exposeHard = !!(softDel && opts.exposeHardDelete);
   const getPkParams = hasCompositePk ? `const pkValues = [${safePkCols.map((c) => `c.req.param("${c}")`).join(", ")}];` : `const pkValues = [c.req.param("${safePkCols[0]}")];`;
   const hasAuth = opts.authStrategy && opts.authStrategy !== "none";
   const ext = opts.useJsExtensions ? ".js" : "";
@@ -2987,7 +3014,7 @@ function emitHonoRoutes(table, _graph, opts) {
 import { Hono } from "hono";
 import type { Context } from "hono";
 import { z } from "zod";
-import { Insert${Type}Schema, Update${Type}Schema } from "../zod/${fileTableName}${ext}";
+import { Insert${Type}Schema, Update${Type}Schema, Upsert${Type}Schema } from "../zod/${fileTableName}${ext}";
 import { loadIncludes } from "../include-loader${ext}";
 import * as coreOps from "../core/operations${ext}";
 ${authImport}
@@ -2996,10 +3023,12 @@ const columnEnum = z.enum([${columnNames}]);
 
 const createSchema = Insert${Type}Schema;
 const updateSchema = Update${Type}Schema;
+const upsertSchema = Upsert${Type}Schema;
 
 const deleteSchema = z.object({
   select: z.array(z.string()).min(1).optional(),
-  exclude: z.array(z.string()).min(1).optional()
+  exclude: z.array(z.string()).min(1).optional(),${exposeHard ? `
+  hard: z.boolean().optional(),` : ""}
 }).strict().refine(
   (data) => !(data.select && data.exclude),
   { message: "Cannot specify both 'select' and 'exclude' parameters" }
@@ -3222,6 +3251,39 @@ ${hasAuth ? `
     }, result.status as any);
   });
 
+  // UPSERT
+  app.post(\`\${base}/upsert\`, async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const parsed = upsertSchema.safeParse(body);
+
+    if (!parsed.success) {
+      const issues = parsed.error.flatten();
+      return c.json({ error: "Invalid body", issues }, 400);
+    }
+
+    const selectParam = c.req.query("select");
+    const excludeParam = c.req.query("exclude");
+    const select = selectParam ? selectParam.split(",") : undefined;
+    const exclude = excludeParam ? excludeParam.split(",") : undefined;
+
+    if (select && exclude) {
+      return c.json({ error: "Cannot specify both 'select' and 'exclude' parameters" }, 400);
+    }
+
+    if (deps.onRequest) {
+      await deps.onRequest(c, deps.pg);
+    }
+
+    const ctx = { ...baseCtx, select, exclude };
+    const result = await coreOps.upsertRecord(ctx, parsed.data);
+
+    if (result.error) {
+      return c.json({ error: result.error }, result.status as any);
+    }
+
+    return c.json(result.data, result.status as any);
+  });
+
   // UPDATE
   app.patch(\`\${base}/${pkPath}\`, async (c) => {
     ${getPkParams}
@@ -3261,13 +3323,15 @@ ${hasAuth ? `
   app.delete(\`\${base}/${pkPath}\`, async (c) => {
     ${getPkParams}
 
-    // Parse query params for select/exclude
+    // Parse query params for select/exclude${exposeHard ? " and hard" : ""}
     const selectParam = c.req.query("select");
     const excludeParam = c.req.query("exclude");
     const queryData: any = {};
     if (selectParam) queryData.select = selectParam.split(",");
     if (excludeParam) queryData.exclude = excludeParam.split(",");
-
+${exposeHard ? `    const hardParam = c.req.query("hard");
+    if (hardParam !== undefined) queryData.hard = hardParam === "true";
+` : ""}
     const queryParsed = deleteSchema.safeParse(queryData);
     if (!queryParsed.success) {
       const issues = queryParsed.error.flatten();
@@ -3279,7 +3343,7 @@ ${hasAuth ? `
     }
 
     const ctx = { ...baseCtx, select: queryParsed.data.select, exclude: queryParsed.data.exclude };
-    const result = await coreOps.deleteRecord(ctx, pkValues);
+    const result = await coreOps.deleteRecord(ctx, pkValues${exposeHard ? ", { hard: queryParsed.data.hard }" : ""});
 
     if (result.error) {
       return c.json({ error: result.error }, result.status as any);
@@ -3294,14 +3358,6 @@ ${hasAuth ? `
 // src/emit-client.ts
 init_utils();
 init_emit_include_methods();
-function isVectorType2(pgType) {
-  const t = pgType.toLowerCase();
-  return t === "vector" || t === "halfvec" || t === "sparsevec" || t === "bit";
-}
-function isJsonbType2(pgType) {
-  const t = pgType.toLowerCase();
-  return t === "json" || t === "jsonb";
-}
 function toIncludeParamName(relationKey) {
   return `${relationKey}Include`;
 }
@@ -3324,10 +3380,12 @@ function emitClient(table, graph, opts, model) {
   const Type = pascal(table.name);
   const ext = opts.useJsExtensions ? ".js" : "";
   const trigramParamType = `{ field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number } | { fields: string[]; strategy?: "greatest" | "concat"; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number } | { fields: Array<{ field: string; weight: number }>; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number }`;
-  const hasVectorColumns = table.columns.some((c) => isVectorType2(c.pgType));
-  const hasJsonbColumns = table.columns.some((c) => isJsonbType2(c.pgType));
+  const hasVectorColumns = table.columns.some((c) => isVectorType(c.pgType));
+  const hasJsonbColumns = table.columns.some((c) => isJsonbType(c.pgType));
+  const hasSoftDelete = !!opts.softDeleteColumn;
+  const exposeHard = !hasSoftDelete || (opts.exposeHardDelete ?? true);
   if (process.env.SDK_DEBUG) {
-    const vectorCols = table.columns.filter((c) => isVectorType2(c.pgType));
+    const vectorCols = table.columns.filter((c) => isVectorType(c.pgType));
     if (vectorCols.length > 0) {
       console.log(`[DEBUG] Table ${table.name}: Found ${vectorCols.length} vector columns:`, vectorCols.map((c) => `${c.name} (${c.pgType})`));
     }
@@ -3343,15 +3401,19 @@ function emitClient(table, graph, opts, model) {
     skipJunctionTables: opts.skipJunctionTables ?? true
   }, allTables);
   const importedTypes = new Set;
+  const usedIncludeSpecTypes = new Set([table.name]);
   importedTypes.add(table.name);
   for (const method of includeMethods) {
     for (const target of method.targets) {
       importedTypes.add(target);
     }
+    const pattern = analyzeIncludeSpec(method.includeSpec);
+    if (pattern.type === "nested" && method.targets[0]) {
+      usedIncludeSpecTypes.add(method.targets[0]);
+    }
   }
   const typeImports = `import type { Insert${Type}, Update${Type}, Select${Type} } from "./types/${table.name}${ext}";`;
-  const includeSpecTypes = [table.name, ...Array.from(importedTypes).filter((t) => t !== table.name)];
-  const includeSpecImport = `import type { ${includeSpecTypes.map((t) => `${pascal(t)}IncludeSpec`).join(", ")} } from "./include-spec${ext}";`;
+  const includeSpecImport = `import type { ${Array.from(usedIncludeSpecTypes).map((t) => `${pascal(t)}IncludeSpec`).join(", ")} } from "./include-spec${ext}";`;
   const includeResolverImport = `import type { ${Type}WithIncludes } from "./include-resolver${ext}";`;
   const otherTableImports = [];
   for (const target of Array.from(importedTypes)) {
@@ -3553,6 +3615,54 @@ function emitClient(table, graph, opts, model) {
 `;
     }
   }
+  const buildDeleteMethod = (methodName, setHardTrue) => {
+    const actionName = methodName === "softDelete" ? "Soft-delete" : "Hard-delete (permanently remove)";
+    const hardLine = setHardTrue ? `
+    queryParams.set('hard', 'true');` : "";
+    const pksLabel = hasCompositePk ? "s" : "";
+    const G = hasJsonbColumns ? `<TJsonb extends Partial<Select${Type}> = {}>` : "";
+    const RBase = hasJsonbColumns ? `Select${Type}<TJsonb>` : `Select${Type}`;
+    const RPart = hasJsonbColumns ? `Partial<Select${Type}<TJsonb>>` : `Partial<Select${Type}>`;
+    return `  /**
+` + `   * ${actionName} a ${table.name} record by primary key with field selection
+` + `   * @param pk - The primary key value${pksLabel}
+` + `   * @param options - Select specific fields to return
+` + `   * @returns The deleted record with only selected fields if found, null otherwise
+` + `   */
+` + `  async ${methodName}${G}(pk: ${pkType}, options: { select: string[] }): Promise<${RPart} | null>;
+` + `  /**
+` + `   * ${actionName} a ${table.name} record by primary key with field exclusion
+` + `   * @param pk - The primary key value${pksLabel}
+` + `   * @param options - Exclude specific fields from return
+` + `   * @returns The deleted record without excluded fields if found, null otherwise
+` + `   */
+` + `  async ${methodName}${G}(pk: ${pkType}, options: { exclude: string[] }): Promise<${RPart} | null>;
+` + `  /**
+` + `   * ${actionName} a ${table.name} record by primary key
+` + `   * @param pk - The primary key value${pksLabel}
+` + `   * @returns The deleted record with all fields if found, null otherwise
+` + `   */
+` + `  async ${methodName}${G}(pk: ${pkType}, options?: Omit<{ select?: string[]; exclude?: string[] }, 'select' | 'exclude'>): Promise<${RBase} | null>;
+` + `  async ${methodName}${G}(
+` + `    pk: ${pkType},
+` + `    options?: { select?: string[]; exclude?: string[] }
+` + `  ): Promise<${RBase} | ${RPart} | null> {
+` + `    const path = ${pkPathExpr};
+` + `    const queryParams = new URLSearchParams();${hardLine}
+` + `    if (options?.select) queryParams.set('select', options.select.join(','));
+` + `    if (options?.exclude) queryParams.set('exclude', options.exclude.join(','));
+` + `    const query = queryParams.toString();
+` + "    const url = query ? `${this.resource}/${path}?${query}` : `${this.resource}/${path}`;\n" + `    return this.del<${RBase} | null>(url);
+` + `  }`;
+  };
+  const deleteMethodParts = [];
+  if (hasSoftDelete)
+    deleteMethodParts.push(buildDeleteMethod("softDelete", false));
+  if (exposeHard)
+    deleteMethodParts.push(buildDeleteMethod("hardDelete", hasSoftDelete));
+  const deleteMethodsCode = deleteMethodParts.join(`
+
+`);
   return `/**
  * AUTO-GENERATED FILE - DO NOT EDIT
  *
@@ -3562,6 +3672,7 @@ function emitClient(table, graph, opts, model) {
  * To make changes, modify your schema or configuration and regenerate.
  */
 import { BaseClient } from "./base-client${ext}";
+import type { TxOp } from "./base-client${ext}";
 import type { Where } from "./where-types${ext}";
 import type { PaginatedResponse } from "./types/shared${ext}";
 ${typeImports}
@@ -3643,6 +3754,78 @@ ${hasJsonbColumns ? `  /**
     return this.post<Select${Type}>(url, data);
   }`}
 
+${hasJsonbColumns ? `  /**
+   * Upsert a ${table.name} record with field selection
+   */
+  async upsert<TJsonb extends Partial<Select${Type}> = {}>(
+    args: { where: Update${Type}<TJsonb>; create: NoInfer<Insert${Type}<TJsonb>>; update: NoInfer<Update${Type}<TJsonb>> },
+    options: { select: string[] }
+  ): Promise<Partial<Select${Type}<TJsonb>>>;
+  /**
+   * Upsert a ${table.name} record with field exclusion
+   */
+  async upsert<TJsonb extends Partial<Select${Type}> = {}>(
+    args: { where: Update${Type}<TJsonb>; create: NoInfer<Insert${Type}<TJsonb>>; update: NoInfer<Update${Type}<TJsonb>> },
+    options: { exclude: string[] }
+  ): Promise<Partial<Select${Type}<TJsonb>>>;
+  /**
+   * Upsert a ${table.name} record — insert if no conflict on 'where' columns, update otherwise.
+   * @param args.where - Conflict target column(s) (must be a unique constraint)
+   * @param args.create - Full insert data used when no conflict occurs
+   * @param args.update - Partial data applied when a conflict occurs
+   * @returns The resulting record
+   */
+  async upsert<TJsonb extends Partial<Select${Type}> = {}>(
+    args: { where: Update${Type}<TJsonb>; create: NoInfer<Insert${Type}<TJsonb>>; update: NoInfer<Update${Type}<TJsonb>> },
+    options?: Omit<{ select?: string[]; exclude?: string[] }, 'select' | 'exclude'>
+  ): Promise<Select${Type}<TJsonb>>;
+  async upsert<TJsonb extends Partial<Select${Type}> = {}>(
+    args: { where: Update${Type}<TJsonb>; create: NoInfer<Insert${Type}<TJsonb>>; update: NoInfer<Update${Type}<TJsonb>> },
+    options?: { select?: string[]; exclude?: string[] }
+  ): Promise<Select${Type}<TJsonb> | Partial<Select${Type}<TJsonb>>> {
+    const queryParams = new URLSearchParams();
+    if (options?.select) queryParams.set('select', options.select.join(','));
+    if (options?.exclude) queryParams.set('exclude', options.exclude.join(','));
+    const query = queryParams.toString();
+    const url = query ? \`\${this.resource}/upsert?\${query}\` : \`\${this.resource}/upsert\`;
+    return this.post<Select${Type}<TJsonb>>(url, args);
+  }` : `  /**
+   * Upsert a ${table.name} record with field selection
+   */
+  async upsert(
+    args: { where: Update${Type}; create: Insert${Type}; update: Update${Type} },
+    options: { select: string[] }
+  ): Promise<Partial<Select${Type}>>;
+  /**
+   * Upsert a ${table.name} record with field exclusion
+   */
+  async upsert(
+    args: { where: Update${Type}; create: Insert${Type}; update: Update${Type} },
+    options: { exclude: string[] }
+  ): Promise<Partial<Select${Type}>>;
+  /**
+   * Upsert a ${table.name} record — insert if no conflict on 'where' columns, update otherwise.
+   * @param args.where - Conflict target column(s) (must be a unique constraint)
+   * @param args.create - Full insert data used when no conflict occurs
+   * @param args.update - Partial data applied when a conflict occurs
+   * @returns The resulting record
+   */
+  async upsert(
+    args: { where: Update${Type}; create: Insert${Type}; update: Update${Type} },
+    options?: Omit<{ select?: string[]; exclude?: string[] }, 'select' | 'exclude'>
+  ): Promise<Select${Type}>;
+  async upsert(
+    args: { where: Update${Type}; create: Insert${Type}; update: Update${Type} },
+    options?: { select?: string[]; exclude?: string[] }
+  ): Promise<Select${Type} | Partial<Select${Type}>> {
+    const queryParams = new URLSearchParams();
+    if (options?.select) queryParams.set('select', options.select.join(','));
+    if (options?.exclude) queryParams.set('exclude', options.exclude.join(','));
+    const query = queryParams.toString();
+    const url = query ? \`\${this.resource}/upsert?\${query}\` : \`\${this.resource}/upsert\`;
+    return this.post<Select${Type}>(url, args);
+  }`}
+
 ${hasJsonbColumns ? `  /**
    * Get a ${table.name} record by primary key with field selection
    * @param pk - The primary key value${hasCompositePk ? "s" : ""}
@@ -3983,72 +4166,27 @@ ${hasJsonbColumns ? `  /**
     return this.patch<Select${Type} | null>(url, patch);
   }`}
 
-${hasJsonbColumns ? `  /**
-   * Delete a ${table.name} record by primary key with field selection
-   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
-   * @param options - Select specific fields to return
-   * @returns The deleted record with only selected fields if found, null otherwise
-   */
-  async delete<TJsonb extends Partial<Select${Type}> = {}>(pk: ${pkType}, options: { select: string[] }): Promise<Partial<Select${Type}<TJsonb>> | null>;
-  /**
-   * Delete a ${table.name} record by primary key with field exclusion
-   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
-   * @param options - Exclude specific fields from return
-   * @returns The deleted record without excluded fields if found, null otherwise
-   */
-  async delete<TJsonb extends Partial<Select${Type}> = {}>(pk: ${pkType}, options: { exclude: string[] }): Promise<Partial<Select${Type}<TJsonb>> | null>;
-  /**
-   * Delete a ${table.name} record by primary key
-   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
-   * @returns The deleted record with all fields if found, null otherwise
-   * @example
-   * // With JSONB type override:
-   * const user = await client.delete<{ metadata: Metadata }>('user-id');
-   */
-  async delete<TJsonb extends Partial<Select${Type}> = {}>(pk: ${pkType}, options?: Omit<{ select?: string[]; exclude?: string[] }, 'select' | 'exclude'>): Promise<Select${Type}<TJsonb> | null>;
-  async delete<TJsonb extends Partial<Select${Type}> = {}>(
-    pk: ${pkType},
-    options?: { select?: string[]; exclude?: string[] }
-  ): Promise<Select${Type}<TJsonb> | Partial<Select${Type}<TJsonb>> | null> {
-    const path = ${pkPathExpr};
-    const queryParams = new URLSearchParams();
-    if (options?.select) queryParams.set('select', options.select.join(','));
-    if (options?.exclude) queryParams.set('exclude', options.exclude.join(','));
-    const query = queryParams.toString();
-    const url = query ? \`\${this.resource}/\${path}?\${query}\` : \`\${this.resource}/\${path}\`;
-    return this.del<Select${Type}<TJsonb> | null>(url);
-  }` : `  /**
-   * Delete a ${table.name} record by primary key with field selection
-   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
-   * @param options - Select specific fields to return
-   * @returns The deleted record with only selected fields if found, null otherwise
-   */
-  async delete(pk: ${pkType}, options: { select: string[] }): Promise<Partial<Select${Type}> | null>;
-  /**
-   * Delete a ${table.name} record by primary key with field exclusion
-   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
-   * @param options - Exclude specific fields from return
-   * @returns The deleted record without excluded fields if found, null otherwise
-   */
-  async delete(pk: ${pkType}, options: { exclude: string[] }): Promise<Partial<Select${Type}> | null>;
-  /**
-   * Delete a ${table.name} record by primary key
-   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
-   * @returns The deleted record with all fields if found, null otherwise
-   */
-  async delete(pk: ${pkType}, options?: Omit<{ select?: string[]; exclude?: string[] }, 'select' | 'exclude'>): Promise<Select${Type} | null>;
-  async delete(
-    pk: ${pkType},
-    options?: { select?: string[]; exclude?: string[] }
-  ): Promise<Select${Type} | Partial<Select${Type}> | null> {
-    const path = ${pkPathExpr};
-    const queryParams = new URLSearchParams();
-    if (options?.select) queryParams.set('select', options.select.join(','));
-    if (options?.exclude) queryParams.set('exclude', options.exclude.join(','));
-    const query = queryParams.toString();
-    const url = query ? \`\${this.resource}/\${path}?\${query}\` : \`\${this.resource}/\${path}\`;
-    return this.del<Select${Type} | null>(url);
-  }`}
+${deleteMethodsCode}
+
+  /** Build a lazy CREATE descriptor for use with sdk.$transaction([...]) */
+  $create(data: Insert${Type}): TxOp<Select${Type}> {
+    return { _table: "${table.name}", _op: "create", _data: data as Record<string, unknown> };
+  }
+
+  /** Build a lazy UPDATE descriptor for use with sdk.$transaction([...]) */
+  $update(pk: ${pkType}, data: Update${Type}): TxOp<Select${Type} | null> {
+    return { _table: "${table.name}", _op: "update", _pk: ${hasCompositePk ? "pk as Record<string, unknown>" : "pk"}, _data: data as Record<string, unknown> };
+  }
+
+  /** Build a lazy DELETE descriptor for use with sdk.$transaction([...]) */
+  $delete(pk: ${pkType}): TxOp<Select${Type} | null> {
+    return { _table: "${table.name}", _op: "delete", _pk: ${hasCompositePk ? "pk as Record<string, unknown>" : "pk"} };
+  }
+
+  /** Build a lazy UPSERT descriptor for use with sdk.$transaction([...]) */
+  $upsert(args: { where: Update${Type}; create: Insert${Type}; update: Update${Type} }): TxOp<Select${Type}> {
+    return { _table: "${table.name}", _op: "upsert", _data: args as Record<string, unknown> };
+  }
 ${includeMethodsCode}}
 `;
 }
@@ -4063,7 +4201,9 @@ function emitClientIndex(tables, useJsExtensions, graph, includeOpts) {
  * To make changes, modify your schema or configuration and regenerate.
  */
 `;
-  out += `import type { AuthConfig } from "./base-client${ext}";
+  out += `import { BaseClient } from "./base-client${ext}";
+`;
+  out += `import type { AuthConfig, TxOp } from "./base-client${ext}";
 `;
   for (const t of tables) {
     out += `import { ${pascal(t.name)}Client } from "./${t.name}${ext}";
@@ -4079,7 +4219,7 @@ export type { AuthConfig, HeaderMap, AuthHeadersProvider } from "./base-client${
 `;
   out += ` */
 `;
-  out += `export class SDK {
+  out += `export class SDK extends BaseClient {
 `;
   for (const t of tables) {
     out += `  public ${t.name}: ${pascal(t.name)}Client;
@@ -4089,17 +4229,101 @@ export type { AuthConfig, HeaderMap, AuthHeadersProvider } from "./base-client${
   constructor(cfg: { baseUrl: string; fetch?: typeof fetch; auth?: AuthConfig }) {
 `;
   out += `    const f = cfg.fetch ?? fetch;
+`;
+  out += `    super(cfg.baseUrl, f, cfg.auth);
 `;
   for (const t of tables) {
     out += `    this.${t.name} = new ${pascal(t.name)}Client(cfg.baseUrl, f, cfg.auth);
 `;
   }
   out += `  }
+`;
+  out += `
+`;
+  out += `  /**
+`;
+  out += `   * Execute multiple operations atomically in one PostgreSQL transaction.
+`;
+  out += `   * All ops are validated before BEGIN is issued — fail-fast on bad input.
+`;
+  out += `   *
+`;
+  out += `   * @example
+`;
+  out += `   * const [order, user] = await sdk.$transaction([
+`;
+  out += `   *   sdk.orders.$create({ user_id: 1, total: 99 }),
+`;
+  out += `   *   sdk.users.$update('1', { last_order_at: new Date().toISOString() }),
+`;
+  out += `   * ]);
+`;
+  out += `   */
+`;
+  out += `  async $transaction<const T extends readonly TxOp<unknown>[]>(
+`;
+  out += `    ops: [...T]
+`;
+  out += `  ): Promise<{ [K in keyof T]: T[K] extends TxOp<infer R> ? R : never }> {
+`;
+  out += `    const payload = ops.map(op => ({
+`;
+  out += `      op: op._op,
+`;
+  out += `      table: op._table,
+`;
+  out += `      ...(op._data !== undefined ? { data: op._data } : {}),
+`;
+  out += `      ...(op._pk !== undefined ? { pk: op._pk } : {}),
+`;
+  out += `    }));
+`;
+  out += `
+`;
+  out += `    const res = await this.fetchFn(\`\${this.baseUrl}/v1/transaction\`, {
+`;
+  out += `      method: "POST",
+`;
+  out += `      headers: await this.headers(true),
+`;
+  out += `      body: JSON.stringify({ ops: payload }),
+`;
+  out += `    });
+`;
+  out += `
+`;
+  out += `    if (!res.ok) {
+`;
+  out += `      let errBody: Record<string, unknown> = {};
+`;
+  out += `      try { errBody = await res.json() as Record<string, unknown>; } catch {}
+`;
+  out += `      const err = Object.assign(
+`;
+  out += `        new Error((errBody.error as string | undefined) ?? \`$transaction failed: \${res.status}\`),
+`;
+  out += `        { failedAt: errBody.failedAt as number | undefined, issues: errBody.issues }
+`;
+  out += `      );
+`;
+  out += `      throw err;
+`;
+  out += `    }
+`;
+  out += `
+`;
+  out += `    const json = await res.json() as { results: unknown[] };
+`;
+  out += `    return json.results as unknown as { [K in keyof T]: T[K] extends TxOp<infer R> ? R : never };
+`;
+  out += `  }
 `;
   out += `}
 
 `;
   out += `export { BaseClient } from "./base-client${ext}";
+`;
+  out += `export type { TxOp } from "./base-client${ext}";
 `;
   out += `
 // Include specification types for custom queries
@@ -4300,15 +4524,29 @@ export abstract class BaseClient {
       method: "DELETE",
       headers: await this.headers(),
     });
-    
+
     if (res.status === 404) {
       return null as T;
     }
-    
+
     await this.okOrThrow(res, "DELETE", path);
     return (await res.json()) as T;
   }
 }
+
+/**
+ * Lazy operation descriptor returned by $create/$update/$delete.
+ * \`__resultType\` is a phantom field — never assigned at runtime, exists only
+ * so TypeScript can infer the correct tuple element type inside \`$transaction\`.
+ */
+export type TxOp<T = unknown> = {
+  readonly _table: string;
+  readonly _op: "create" | "update" | "delete" | "upsert";
+  readonly _data?: Record<string, unknown>;
+  readonly _pk?: string | Record<string, unknown>;
+  /** @internal */
+  readonly __resultType?: T;
+};
 `;
 }
 
@@ -4852,14 +5090,14 @@ function tsTypeFor(pgType, opts, enums) {
     return "number[]";
   return "string";
 }
-function isJsonbType3(pgType) {
+function isJsonbType2(pgType) {
   const t = pgType.toLowerCase();
   return t === "json" || t === "jsonb";
 }
 var pascal2 = (s) => s.split(/[_\s-]+/).map((w) => w?.[0] ? w[0].toUpperCase() + w.slice(1) : "").join("");
 function emitTypes(table, opts, enums) {
   const Type = pascal2(table.name);
-  const hasJsonbColumns = table.columns.some((col) => isJsonbType3(col.pgType));
+  const hasJsonbColumns = table.columns.some((col) => isJsonbType2(col.pgType));
   const insertFields = table.columns.map((col) => {
     const base = tsTypeFor(col.pgType, opts, enums);
     const optional = col.hasDefault || col.nullable ? "?" : "";
@@ -5310,9 +5548,12 @@ export async function authMiddleware(c: Context, next: Next) {
 
 // src/emit-router-hono.ts
 init_utils();
-function emitHonoRouter(tables, hasAuth, useJsExtensions, pullToken) {
+function emitHonoRouter(tables, hasAuth, useJsExtensions, pullToken, opts) {
   const tableNames = tables.map((t) => t.name).sort();
   const ext = useJsExtensions ? ".js" : "";
+  const apiPathPrefix = opts?.apiPathPrefix ?? "/v1";
+  const softDeleteCols = opts?.softDeleteCols ?? {};
+  const includeMethodsDepth = opts?.includeMethodsDepth ?? 2;
   let resolvedPullToken;
   let pullTokenEnvVar;
   if (pullToken) {
@@ -5338,6 +5579,88 @@ function emitHonoRouter(tables, hasAuth, useJsExtensions, pullToken) {
     const Type = pascal(name);
     return `export { register${Type}Routes } from "./routes/${name}${ext}";`;
   }).join(`
+`);
+  const txSchemaImports = tableNames.map((name) => {
+    const Type = pascal(name);
+    return `import { Insert${Type}Schema, Update${Type}Schema } from "./zod/${name}${ext}";`;
+  }).join(`
+`);
+  function txRouteBlock(appVar) {
+    const authLine = hasAuth ? `  ${appVar}.use(\`${apiPathPrefix}/transaction\`, authMiddleware);
+` : "";
+    return `${authLine}  ${appVar}.post(\`${apiPathPrefix}/transaction\`, async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const rawOps: unknown[] = Array.isArray(body.ops) ? body.ops : [];
+
+    if (rawOps.length === 0) {
+      return c.json({ error: "ops must be a non-empty array" }, 400);
+    }
+
+    // Validate all ops against their table schemas BEFORE opening a transaction
+    const validatedOps: coreOps.TransactionOperation[] = [];
+    for (let i = 0; i < rawOps.length; i++) {
+      const item = rawOps[i] as any;
+      const entry = TABLE_TX_METADATA[item?.table as string];
+      if (!entry) {
+        return c.json({ error: \`Unknown table "\${item?.table}" at index \${i}\`, failedAt: i }, 400);
+      }
+      if (item.op === "create") {
+        const parsed = entry.insertSchema.safeParse(item.data ?? {});
+        if (!parsed.success) {
+          return c.json({ error: "Validation failed", issues: parsed.error.flatten(), failedAt: i }, 400);
+        }
+        validatedOps.push({ op: "create", table: item.table, data: parsed.data });
+      } else if (item.op === "update") {
+        const parsed = entry.updateSchema.safeParse(item.data ?? {});
+        if (!parsed.success) {
+          return c.json({ error: "Validation failed", issues: parsed.error.flatten(), failedAt: i }, 400);
+        }
+        if (item.pk == null) {
+          return c.json({ error: \`Missing pk at index \${i}\`, failedAt: i }, 400);
+        }
+        validatedOps.push({ op: "update", table: item.table, pk: item.pk, data: parsed.data });
+      } else if (item.op === "delete") {
+        if (item.pk == null) {
+          return c.json({ error: \`Missing pk at index \${i}\`, failedAt: i }, 400);
+        }
+        validatedOps.push({ op: "delete", table: item.table, pk: item.pk });
+      } else {
+        return c.json({ error: \`Unknown op "\${item?.op}" at index \${i}\`, failedAt: i }, 400);
+      }
+    }
+
+    const onBegin = deps.onRequest
+      ? (txClient: typeof deps.pg) => deps.onRequest!(c, txClient)
+      : undefined;
+
+    const result = await coreOps.executeTransaction(deps.pg, validatedOps, TABLE_TX_METADATA, onBegin);
+
+    if (!result.ok) {
+      return c.json({ error: result.error, failedAt: result.failedAt }, 400);
+    }
+    return c.json({ results: result.results.map(r => r.data) }, 200);
+  });`;
+  }
+  const txMetadataEntries = tables.slice().sort((a, b) => a.name.localeCompare(b.name)).map((t) => {
+    const rawPk = t.pk;
+    const pkCols = Array.isArray(rawPk) ? rawPk : rawPk ? [rawPk] : ["id"];
+    const softDel = softDeleteCols[t.name] ?? null;
+    const allCols = t.columns.map((c) => `"${c.name}"`).join(", ");
+    const vecCols = t.columns.filter((c) => isVectorType(c.pgType)).map((c) => `"${c.name}"`).join(", ");
+    const jsonCols = t.columns.filter((c) => isJsonbType(c.pgType)).map((c) => `"${c.name}"`).join(", ");
+    const Type = pascal(t.name);
+    return `  "${t.name}": {
+    table: "${t.name}",
+    pkColumns: ${JSON.stringify(pkCols)},
+    softDeleteColumn: ${softDel ? `"${softDel}"` : "null"},
+    allColumnNames: [${allCols}],
+    vectorColumns: [${vecCols}],
+    jsonbColumns: [${jsonCols}],
+    includeMethodsDepth: ${includeMethodsDepth},
+    insertSchema: Insert${Type}Schema,
+    updateSchema: Update${Type}Schema,
+  }`;
+  }).join(`,
 `);
   return `/**
  * AUTO-GENERATED FILE - DO NOT EDIT
@@ -5351,8 +5674,27 @@ import { Hono } from "hono";
 import type { Context } from "hono";
 import { SDK_MANIFEST } from "./sdk-bundle${ext}";
 import { getContract } from "./contract${ext}";
+import * as coreOps from "./core/operations${ext}";
+${txSchemaImports}
 ${imports}
-${hasAuth ? `export { authMiddleware } from "./auth${ext}";` : ""}
+${hasAuth ? `import { authMiddleware } from "./auth${ext}";
+export { authMiddleware };` : ""}
+
+/** Discriminated result from safeParse — mirrors Zod's actual return shape */
+type SchemaParseResult =
+  | { success: true; data: Record<string, unknown> }
+  | { success: false; error: { flatten: () => unknown } };
+
+/** Registry entry — core metadata + Zod schemas for request validation */
+interface TxTableRegistry extends coreOps.TransactionTableMetadata {
+  insertSchema: { safeParse: (v: unknown) => SchemaParseResult };
+  updateSchema: { safeParse: (v: unknown) => SchemaParseResult };
+}
+
+// Registry used by POST /v1/transaction — maps table name to metadata + Zod schemas
+const TABLE_TX_METADATA: Record<string, TxTableRegistry> = {
+${txMetadataEntries}
+};
 
 /**
  * Creates a Hono router with all generated routes that can be mounted into your existing app.
@@ -5422,7 +5764,7 @@ ${pullToken ? `
     if (!expectedToken) {
       // Token not configured in environment - reject request
       return c.json({
-        error: "SDK endpoints are protected but pullToken environment variable not set. ${pullTokenEnvVar ? `Set ${pullTokenEnvVar} in your environment or remove pullToken from config.` : "Set the pullToken environment variable or remove pullToken from config."}"
+        error: "SDK endpoints are protected but pullToken environment variable not set. ${pullTokenEnvVar ? `Set ${pullTokenEnvVar} in your environment, or remove pullToken from config.` : "Remove pullToken from config or set the expected environment variable."}"
       }, 500);
     }
 
@@ -5439,6 +5781,9 @@ ${pullToken ? `
     await next();
   });
 ` : ""}
+  // Transaction endpoint — executes multiple operations atomically
+${txRouteBlock("router")}
+
   // SDK distribution endpoints
   router.get("/_psdk/sdk/manifest", (c) => {
     return c.json({
@@ -5522,6 +5867,7 @@ export function registerAllRoutes(
   }
 ) {
 ${registrations.replace(/router/g, "app")}
+${txRouteBlock("app")}
 }
 
 // Individual route registrations (for selective use)
@@ -5566,8 +5912,6 @@ function emitCoreOperations() {
  * These functions handle the actual database logic and can be used by any framework adapter.
  */
 
-import type { z } from "zod";
-
 export interface DatabaseClient {
   query: (text: string, params?: any[]) => Promise<{ rows: any[] }>;
 }
@@ -5711,6 +6055,96 @@ export async function createRecord(
   }
 }
 
+/**
+ * UPSERT operation - Insert or update a record based on a conflict target
+ */
+export async function upsertRecord(
+  ctx: OperationContext,
+  args: {
+    where: Record<string, any>;   // conflict target columns (keys only matter)
+    create: Record<string, any>;  // full insert data
+    update: Record<string, any>;  // update data on conflict
+  }
+): Promise<{ data?: any; error?: string; issues?: any; status: number }> {
+  try {
+    const { where, create: createData, update: updateData } = args;
+
+    const conflictCols = Object.keys(where);
+    if (!conflictCols.length) {
+      return { error: "where must specify at least one column", status: 400 };
+    }
+
+    const insertCols = Object.keys(createData);
+    const insertVals = Object.values(createData);
+    if (!insertCols.length) {
+      return { error: "No fields provided in create", status: 400 };
+    }
+
+    // Filter PK columns from update (mirrors updateRecord behaviour)
+    const filteredUpdate = Object.fromEntries(
+      Object.entries(updateData).filter(([k]) => !ctx.pkColumns.includes(k))
+    );
+    if (!Object.keys(filteredUpdate).length) {
+      return { error: "update must include at least one non-PK field", status: 400 };
+    }
+
+    // Serialise JSONB/vector values for create (same pattern as createRecord)
+    const preparedInsertVals = insertVals.map((v, i) =>
+      v !== null && v !== undefined && typeof v === 'object' &&
+      (ctx.jsonbColumns?.includes(insertCols[i]!) || ctx.vectorColumns?.includes(insertCols[i]!))
+        ? JSON.stringify(v) : v
+    );
+
+    // Serialise JSONB/vector values for update
+    const updateCols = Object.keys(filteredUpdate);
+    const updateVals = Object.values(filteredUpdate);
+    const preparedUpdateVals = updateVals.map((v, i) =>
+      v !== null && v !== undefined && typeof v === 'object' &&
+      (ctx.jsonbColumns?.includes(updateCols[i]!) || ctx.vectorColumns?.includes(updateCols[i]!))
+        ? JSON.stringify(v) : v
+    );
+
+    const placeholders  = insertCols.map((_, i) => \`$\${i + 1}\`).join(', ');
+    const conflictSQL   = conflictCols.map(c => \`"\${c}"\`).join(', ');
+    const setSql        = updateCols.map((k, i) => \`"\${k}" = $\${insertCols.length + i + 1}\`).join(', ');
+    const returningClause = buildColumnList(ctx.select, ctx.exclude, ctx.allColumnNames);
+
+    const text = \`INSERT INTO "\${ctx.table}" (\${insertCols.map(c => \`"\${c}"\`).join(', ')})
+                  VALUES (\${placeholders})
+                  ON CONFLICT (\${conflictSQL}) DO UPDATE SET \${setSql}
+                  RETURNING \${returningClause}\`;
+    const params = [...preparedInsertVals, ...preparedUpdateVals];
+
+    log.debug("UPSERT SQL:", text, "params:", params);
+    const { rows } = await ctx.pg.query(text, params);
+    const parsedRows = parseVectorColumns(rows, ctx.vectorColumns);
+
+    if (!parsedRows[0]) {
+      return { data: null, status: 500 };
+    }
+
+    return { data: parsedRows[0], status: 200 };
+  } catch (e: any) {
+    const errorMsg = e?.message ?? "";
+    const isJsonError = errorMsg.includes("invalid input syntax for type json");
+    if (isJsonError) {
+      log.error(\`UPSERT \${ctx.table} - Invalid JSON input detected!\`);
+      log.error("Input args that caused error:", JSON.stringify(args, null, 2));
+      log.error("Filtered update data (sent to DB):", JSON.stringify(Object.fromEntries(
+        Object.entries(args.update).filter(([k]) => !ctx.pkColumns.includes(k))
+      ), null, 2));
+      log.error("PostgreSQL error:", errorMsg);
+    } else {
+      log.error(\`UPSERT \${ctx.table} error:\`, e?.stack ?? e);
+    }
+    return {
+      error: e?.message ?? "Internal error",
+      ...(DEBUG ? { stack: e?.stack } : {}),
+      status: 500
+    };
+  }
+}
+
 /**
  * READ operation - Get a record by primary key
  */
@@ -6387,7 +6821,8 @@ export async function updateRecord(
  */
 export async function deleteRecord(
   ctx: OperationContext,
-  pkValues: any[]
+  pkValues: any[],
+  opts?: { hard?: boolean }
 ): Promise<{ data?: any; error?: string; status: number }> {
   try {
     const hasCompositePk = ctx.pkColumns.length > 1;
@@ -6396,11 +6831,12 @@ export async function deleteRecord(
       : \`"\${ctx.pkColumns[0]}" = $1\`;
 
     const returningClause = buildColumnList(ctx.select, ctx.exclude, ctx.allColumnNames);
-    const text = ctx.softDeleteColumn
+    const doSoftDelete = ctx.softDeleteColumn && !opts?.hard;
+    const text = doSoftDelete
       ? \`UPDATE "\${ctx.table}" SET "\${ctx.softDeleteColumn}" = NOW() WHERE \${wherePkSql} RETURNING \${returningClause}\`
       : \`DELETE FROM "\${ctx.table}" WHERE \${wherePkSql} RETURNING \${returningClause}\`;
 
-    log.debug(\`DELETE \${ctx.softDeleteColumn ? '(soft)' : ''} \${ctx.table} SQL:\`, text, "pk:", pkValues);
+    log.debug(\`DELETE \${doSoftDelete ? '(soft)' : ''} \${ctx.table} SQL:\`, text, "pk:", pkValues);
     const { rows } = await ctx.pg.query(text, pkValues);
     const parsedRows = parseVectorColumns(rows, ctx.vectorColumns);
 
@@ -6411,12 +6847,123 @@ export async function deleteRecord(
     return { data: parsedRows[0], status: 200 };
   } catch (e: any) {
     log.error(\`DELETE \${ctx.table} error:\`, e?.stack ?? e);
-    return { 
-      error: e?.message ?? "Internal error", 
+    return {
+      error: e?.message ?? "Internal error",
       ...(DEBUG ? { stack: e?.stack } : {}),
-      status: 500 
+      status: 500
     };
   }
+}
+
+/**
+ * Static metadata for a table used during transaction execution.
+ * Mirrors the fields needed to construct an OperationContext (minus the pg client,
+ * which is injected at transaction time).
+ */
+export interface TransactionTableMetadata {
+  table: string;
+  pkColumns: string[];
+  softDeleteColumn: string | null;
+  allColumnNames: string[];
+  vectorColumns: string[];
+  jsonbColumns: string[];
+  includeMethodsDepth: number;
+}
+
+export type TransactionOperation =
+  | { op: "create"; table: string; data: Record<string, unknown> }
+  | { op: "update"; table: string; pk: string | Record<string, unknown>; data: Record<string, unknown> }
+  | { op: "delete"; table: string; pk: string | Record<string, unknown> }
+  | { op: "upsert"; table: string; data: { where: Record<string, unknown>; create: Record<string, unknown>; update: Record<string, unknown> } };
+
+/**
+ * Executes a list of operations atomically inside a single PostgreSQL transaction.
+ *
+ * - When \`pg\` has a \`.connect()\` method (Pool), acquires a dedicated connection.
+ * - Otherwise uses \`pg\` directly (already a single connected Client).
+ * - Calls \`onBegin(txClient)\` after BEGIN and before any operations (for SET LOCAL etc.).
+ * - Any status >= 400 or thrown error triggers ROLLBACK.
+ * - \`failedAt: -1\` indicates an unexpected exception (e.g. connectivity failure).
+ */
+export async function executeTransaction(
+  pg: DatabaseClient & { connect?: () => Promise<DatabaseClient & { release?: () => void }> },
+  ops: TransactionOperation[],
+  metadata: Record<string, TransactionTableMetadata>,
+  onBegin?: (txClient: DatabaseClient) => Promise<void>
+): Promise<
+  | { ok: true; results: Array<{ data: unknown }> }
+  | { ok: false; error: string; failedAt: number }
+> {
+  // Fail-fast: validate all table names before touching the DB
+  for (let i = 0; i < ops.length; i++) {
+    if (!metadata[ops[i]!.table]) {
+      return { ok: false, error: \`Unknown table "\${ops[i]!.table}"\`, failedAt: i };
+    }
+  }
+
+  // Pool gives a dedicated connection; plain Client is used directly
+  const isPool = typeof (pg as any).connect === "function";
+  const txClient: DatabaseClient & { release?: () => void } = isPool
+    ? await (pg as any).connect()
+    : pg;
+
+  try {
+    await txClient.query("BEGIN");
+    if (onBegin) await onBegin(txClient);
+
+    const results: Array<{ data: unknown }> = [];
+
+    for (let i = 0; i < ops.length; i++) {
+      const op = ops[i]!;
+      const meta = metadata[op.table]!;
+      const ctx: OperationContext = {
+        pg: txClient,
+        table: meta.table,
+        pkColumns: meta.pkColumns,
+        softDeleteColumn: meta.softDeleteColumn,
+        allColumnNames: meta.allColumnNames,
+        vectorColumns: meta.vectorColumns,
+        jsonbColumns: meta.jsonbColumns,
+        includeMethodsDepth: meta.includeMethodsDepth,
+      };
+
+      let result: { data?: unknown; error?: string; status: number };
+
+      if (op.op === "create") {
+        result = await createRecord(ctx, op.data);
+      } else if (op.op === "upsert") {
+        result = await upsertRecord(ctx, op.data);
+      } else {
+        const pkValues = Array.isArray(op.pk)
+          ? op.pk
+          : typeof op.pk === "object" && op.pk !== null
+          ? meta.pkColumns.map(c => (op.pk as Record<string, unknown>)[c])
+          : [op.pk];
+        result = op.op === "update"
+          ? await updateRecord(ctx, pkValues as string[], op.data)
+          : await deleteRecord(ctx, pkValues as string[]);
+      }
+
+      if (result.status >= 400) {
+        try { await txClient.query("ROLLBACK"); } catch {}
+        txClient.release?.();
+        return {
+          ok: false,
+          error: result.error ?? \`Op \${i} returned status \${result.status}\`,
+          failedAt: i,
+        };
+      }
+      results.push({ data: result.data ?? null });
+    }
+
+    await txClient.query("COMMIT");
+    txClient.release?.();
+    return { ok: true, results };
+  } catch (e: unknown) {
+    try { await txClient.query("ROLLBACK"); } catch {}
+    txClient.release?.();
+    return { ok: false, error: (e instanceof Error ? e.message : String(e)) ?? "Transaction error", failedAt: -1 };
+  }
 }`;
 }
 
@@ -6848,7 +7395,7 @@ function generateForeignKeySetup(table, model, clientPath) {
     // Clean up parent ${foreignTableName} record
     if (${foreignTableName}Id) {
       try {
-        await sdk.${foreignTableName}.delete(${foreignTableName}Id);
+        await sdk.${foreignTableName}.hardDelete(${foreignTableName}Id);
       } catch (e) {
         // Parent might already be deleted due to cascading
       }
@@ -6865,7 +7412,7 @@ function generateForeignKeySetup(table, model, clientPath) {
     // Clean up parent ${foreignTableName} record
     if (${foreignTableName}Key) {
       try {
-        await sdk.${foreignTableName}.delete(${foreignTableName}Key);
+        await sdk.${foreignTableName}.hardDelete(${foreignTableName}Key);
       } catch (e) {
         // Parent might already be deleted due to cascading
       }
@@ -7130,19 +7677,34 @@ function generateTestCases(table, sampleData, updateData, hasForeignKeys = false
       console.warn('No ID from create test, skipping update test');
       return;
     }
-    
+
     const updateData: Update${Type} = ${updateData};
     const updated = await sdk.${table.name}.update(createdId, updateData);
     expect(updated).toBeDefined();
+  });
+
+  it('should upsert (update path) ${table.name}', async () => {
+    if (!createdId) {
+      console.warn('No ID from create test, skipping upsert test');
+      return;
+    }
+    // where: use PK as conflict target; create includes PK so conflict is guaranteed
+    const result = await sdk.${table.name}.upsert({
+      where: { ${table.pk[0]}: createdId },
+      create: { ${table.pk[0]}: createdId, ...${sampleData} },
+      update: ${updateData},
+    });
+    expect(result).toBeDefined();
+    expect(result.${table.pk[0]}).toBe(createdId);
   });` : ""}
-  
+
   it('should delete ${table.name}', async () => {
     if (!createdId) {
       console.warn('No ID from create test, skipping delete test');
       return;
     }
     
-    const deleted = await sdk.${table.name}.delete(createdId);
+    const deleted = await sdk.${table.name}.hardDelete(createdId);
     expect(deleted).toBeDefined();
     
     // Verify deletion
@@ -7159,10 +7721,16 @@ var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = dirname2(__filename2);
 var { version: CLI_VERSION } = JSON.parse(readFileSync(join2(__dirname2, "../package.json"), "utf-8"));
 function resolveSoftDeleteColumn(cfg, tableName) {
-  const overrides = cfg.softDeleteColumnOverrides;
+  const del = cfg.delete;
+  if (!del)
+    return null;
+  const overrides = del.softDeleteColumnOverrides;
   if (overrides && tableName in overrides)
     return overrides[tableName] ?? null;
-  return cfg.softDeleteColumn ?? null;
+  return del.softDeleteColumn ?? null;
+}
+function resolveExposeHardDelete(cfg) {
+  return cfg.delete?.exposeHardDelete ?? true;
 }
 async function generate(configPath, options) {
   if (!existsSync2(configPath)) {
@@ -7252,6 +7820,7 @@ async function generate(configPath, options) {
     path: join2(serverDir, "core", "operations.ts"),
     content: emitCoreOperations()
   });
+  const exposeHardDelete = resolveExposeHardDelete(cfg);
   if (process.env.SDK_DEBUG) {
     console.log(`[Index] About to process ${Object.keys(model.tables || {}).length} tables for generation`);
   }
@@ -7269,6 +7838,7 @@ async function generate(configPath, options) {
     if (serverFramework === "hono") {
       routeContent = emitHonoRoutes(table, graph, {
         softDeleteColumn: softDeleteCols[table.name] ?? null,
+        exposeHardDelete,
         includeMethodsDepth: cfg.includeMethodsDepth || 2,
         authStrategy: getAuthStrategy(normalizedAuth),
         useJsExtensions: cfg.useJsExtensions,
@@ -7284,6 +7854,8 @@ async function generate(configPath, options) {
     files.push({
       path: join2(clientDir, `${table.name}.ts`),
       content: emitClient(table, graph, {
+        softDeleteColumn: softDeleteCols[table.name] ?? null,
+        exposeHardDelete,
         useJsExtensions: cfg.useJsExtensionsClient,
         includeMethodsDepth: cfg.includeMethodsDepth ?? 2,
         skipJunctionTables: cfg.skipJunctionTables ?? true
@@ -7297,7 +7869,11 @@ async function generate(configPath, options) {
   if (serverFramework === "hono") {
     files.push({
       path: join2(serverDir, "router.ts"),
-      content: emitHonoRouter(Object.values(model.tables), getAuthStrategy(normalizedAuth) !== "none", cfg.useJsExtensions, cfg.pullToken)
+      content: emitHonoRouter(Object.values(model.tables), getAuthStrategy(normalizedAuth) !== "none", cfg.useJsExtensions, cfg.pullToken, {
+        apiPathPrefix: cfg.apiPathPrefix || "/v1",
+        softDeleteCols: Object.fromEntries(Object.values(model.tables).map((t) => [t.name, resolveSoftDeleteColumn(cfg, t.name)])),
+        includeMethodsDepth: cfg.includeMethodsDepth ?? 2
+      })
     });
   }
   const { generateUnifiedContract: generateUnifiedContract2, generateUnifiedContractMarkdown: generateUnifiedContractMarkdown2 } = await Promise.resolve().then(() => (init_emit_sdk_contract(), exports_emit_sdk_contract));