postgresdk 0.18.19 → 0.18.21

package/README.md

@@ -680,6 +680,16 @@ const sorted = await sdk.users.list({
   order: ["asc", "desc"]  // or use single direction: order: "asc"
 });
 
+// DISTINCT ON - one row per unique value (PostgreSQL)
+const latestPerUser = await sdk.events.list({
+  distinctOn: "user_id",             // or array: ["user_id", "type"]
+  orderBy: "created_at",
+  order: "desc"
+});
+// Returns one event per user_id, ordered by created_at DESC.
+// When orderBy contains columns outside of distinctOn, a subquery is used
+// automatically so the outer ordering is always respected.
+
 // Advanced WHERE operators
 const filtered = await sdk.users.list({
   where: {
@@ -900,7 +910,80 @@ const uniqueResults = Array.from(
 
 **Note:** Vector columns are auto-detected during introspection. Rows with `NULL` embeddings are excluded from vector search results.
 
-See the generated SDK documentation for all available operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$like`, `$ilike`, `$is`, `$isNot`, `$or`, `$and`, `$jsonbContains`, `$jsonbContainedBy`, `$jsonbHasKey`, `$jsonbHasAnyKeys`, `$jsonbHasAllKeys`, `$jsonbPath`.
+#### Trigram Search (pg_trgm)
+
+PostgreSDK supports full-text fuzzy search via [pg_trgm](https://www.postgresql.org/docs/current/pgtrgm.html). Requires the `pg_trgm` extension installed.
+
+```sql
+CREATE EXTENSION IF NOT EXISTS "pg_trgm";
+```
+
+```typescript
+// Basic trigram similarity search on a text field
+const results = await sdk.books.list({
+  trigram: {
+    field: "title",
+    query: "postgrs",          // typo-tolerant fuzzy match
+    metric: "similarity",      // "similarity" (default), "wordSimilarity", "strictWordSimilarity"
+    threshold: 0.3             // optional: exclude rows below this score (0–1)
+  },
+  limit: 10
+});
+
+// _similarity score is automatically included in each result
+results.data.forEach(book => {
+  console.log(book.title, book._similarity);
+});
+
+// Combine with WHERE filters
+const filtered = await sdk.books.list({
+  trigram: { field: "title", query: "postgrs", threshold: 0.2 },
+  where: { published: true },
+  limit: 20
+});
+```
+
+**Similarity Metrics:**
+- `similarity` (default): Standard trigram similarity — `"col" % value`. Fraction of matching trigrams.
+- `wordSimilarity`: Highest similarity between the query and any word in the column — `value <% "col"`.
+- `strictWordSimilarity`: Strict word similarity — `value <<% "col"`. Requires the query to match an entire word.
+
+**Inline `where` operators (without a top-level `trigram` param):**
+```typescript
+// Filter by trigram similarity inside a where clause
+const results = await sdk.books.list({
+  where: {
+    title: { $similarity: "postgrs" }          // % operator
+    // title: { $wordSimilarity: "postgrs" }   // <% operator
+    // title: { $strictWordSimilarity: "postgrs" } // <<% operator
+  }
+});
+```
+
+**Multi-field trigram search:**
+```typescript
+// Greatest strategy (default): score = GREATEST(sim(name), sim(url))
+const results = await sdk.websites.list({
+  trigram: { fields: ["name", "url"], query: "google", strategy: "greatest" }
+});
+
+// Concat strategy: concatenate fields before scoring ("name url")
+const results = await sdk.websites.list({
+  trigram: { fields: ["name", "url"], query: "google", strategy: "concat" }
+});
+
+// Weighted strategy: weighted average of per-field scores
+const results = await sdk.websites.list({
+  trigram: {
+    fields: [{ field: "name", weight: 2 }, { field: "url", weight: 1 }],
+    query: "google"
+  }
+});
+```
+
+**Note:** `trigram` and `vector` are mutually exclusive on a single `list()` call.
+
+See the generated SDK documentation for all available operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$like`, `$ilike`, `$similarity`, `$wordSimilarity`, `$strictWordSimilarity`, `$is`, `$isNot`, `$or`, `$and`, `$jsonbContains`, `$jsonbContainedBy`, `$jsonbHasKey`, `$jsonbHasAnyKeys`, `$jsonbHasAllKeys`, `$jsonbPath`.
 
 ---
 

package/dist/cli.js

@@ -3228,6 +3228,7 @@ function emitHonoRoutes(table, _graph, opts) {
   const fileTableName = table.name;
   const Type = pascal(table.name);
   const hasVectorColumns = table.columns.some((c) => isVectorType(c.pgType));
+  const trigramMetricZod = `z.enum(["similarity", "wordSimilarity", "strictWordSimilarity"]).optional()`;
   const vectorColumns = table.columns.filter((c) => isVectorType(c.pgType)).map((c) => c.name);
   const jsonbColumns = table.columns.filter((c) => isJsonbType(c.pgType)).map((c) => c.name);
   const rawPk = table.pk;
@@ -3293,7 +3294,28 @@ const listSchema = z.object({
     query: z.array(z.number()),
     metric: z.enum(["cosine", "l2", "inner"]).optional(),
     maxDistance: z.number().optional()
-  }).optional()` : ""}
+  }).optional(),` : ""}
+  trigram: z.union([
+    z.object({
+      field: z.string(),
+      query: z.string(),
+      metric: ${trigramMetricZod},
+      threshold: z.number().min(0).max(1).optional()
+    }),
+    z.object({
+      fields: z.array(z.string()).min(1),
+      strategy: z.enum(["greatest", "concat"]).optional(),
+      query: z.string(),
+      metric: ${trigramMetricZod},
+      threshold: z.number().min(0).max(1).optional()
+    }),
+    z.object({
+      fields: z.array(z.object({ field: z.string(), weight: z.number().positive() })).min(1),
+      query: z.string(),
+      metric: ${trigramMetricZod},
+      threshold: z.number().min(0).max(1).optional()
+    })
+  ]).optional()
 }).strict().refine(
   (data) => !(data.select && data.exclude),
   { message: "Cannot specify both 'select' and 'exclude' parameters" }
@@ -3561,6 +3583,7 @@ function analyzeIncludeSpec(includeSpec) {
 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));
   if (process.env.SDK_DEBUG) {
@@ -3964,10 +3987,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<Partial<Select${Type}<TJsonb>>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<Partial<Select${Type}<TJsonb>> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   /**
    * List ${table.name} records with field exclusion
    * @param params - Query parameters with exclude
@@ -3985,10 +4009,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<Partial<Select${Type}<TJsonb>>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<Partial<Select${Type}<TJsonb>> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   /**
    * List ${table.name} records with pagination and filtering
    * @param params - Query parameters
@@ -4017,10 +4042,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   async list<TJsonb extends Partial<Select${Type}> = {}>(params?: {
     include?: ${Type}IncludeSpec;
     select?: string[];
@@ -4034,11 +4060,12 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
   }): Promise<PaginatedResponse<Select${Type}<TJsonb> | Partial<Select${Type}<TJsonb>>>> {
-    return this.post<PaginatedResponse<Select${Type}<TJsonb>${hasVectorColumns ? " & { _distance?: number }" : ""}>>(\`\${this.resource}/list\`, params ?? {});
+    return this.post<PaginatedResponse<Select${Type}<TJsonb> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>(\`\${this.resource}/list\`, params ?? {});
   }` : `  /**
    * List ${table.name} records with field selection
    * @param params - Query parameters with select
@@ -4056,10 +4083,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<Partial<Select${Type}>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<Partial<Select${Type}> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   /**
    * List ${table.name} records with field exclusion
    * @param params - Query parameters with exclude
@@ -4077,10 +4105,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<Partial<Select${Type}>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<Partial<Select${Type}> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   /**
    * List ${table.name} records with pagination and filtering
    * @param params - Query parameters
@@ -4103,10 +4132,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   async list(params?: {
     include?: ${Type}IncludeSpec;
     select?: string[];
@@ -4120,11 +4150,12 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
   }): Promise<PaginatedResponse<Select${Type} | Partial<Select${Type}>>> {
-    return this.post<PaginatedResponse<Select${Type}${hasVectorColumns ? " & { _distance?: number }" : ""}>>(\`\${this.resource}/list\`, params ?? {});
+    return this.post<PaginatedResponse<Select${Type} & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>(\`\${this.resource}/list\`, params ?? {});
   }`}
 
 ${hasJsonbColumns ? `  /**
@@ -5292,6 +5323,12 @@ export type WhereOperator<T> = {
   $like?: T extends string ? string : never;
   /** Case-insensitive LIKE (strings only) */
   $ilike?: T extends string ? string : never;
+  /** Trigram similarity match - "col" % value (pg_trgm required, uses similarity_threshold GUC) */
+  $similarity?: T extends string ? string : never;
+  /** Word trigram similarity match - value <% "col" (pg_trgm required) */
+  $wordSimilarity?: T extends string ? string : never;
+  /** Strict word trigram similarity match - value <<% "col" (pg_trgm required) */
+  $strictWordSimilarity?: T extends string ? string : never;
   /** IS NULL */
   $is?: null;
   /** IS NOT NULL */
@@ -5908,7 +5945,7 @@ export async function createRecord(
 
     const preparedVals = vals.map((v, i) =>
       v !== null && v !== undefined && typeof v === 'object' &&
-      (ctx.jsonbColumns?.includes(cols[i]) || ctx.vectorColumns?.includes(cols[i]))
+      (ctx.jsonbColumns?.includes(cols[i]!) || ctx.vectorColumns?.includes(cols[i]!))
         ? JSON.stringify(v)
         : v
     );
@@ -6068,6 +6105,24 @@ function buildWhereClause(
             whereParams.push(opValue);
             paramIndex++;
             break;
+          case '$similarity':
+            // pg_trgm: boolean similarity operator (respects similarity_threshold GUC)
+            whereParts.push(\`"\${key}" % $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$wordSimilarity':
+            // pg_trgm: word similarity operator (value <% col)
+            whereParts.push(\`$\${paramIndex} <% "\${key}"\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$strictWordSimilarity':
+            // pg_trgm: strict word similarity operator (value <<% col)
+            whereParts.push(\`$\${paramIndex} <<% "\${key}"\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
           case '$is':
             if (opValue === null) {
               whereParts.push(\`"\${key}" IS NULL\`);
@@ -6241,6 +6296,53 @@ function getVectorDistanceOperator(metric?: string): string {
   }
 }
 
+export type TrigramMetric = "similarity" | "wordSimilarity" | "strictWordSimilarity";
+
+export type TrigramParam =
+  | { field: string; query: string; metric?: TrigramMetric; threshold?: number }
+  | { fields: string[]; strategy?: "greatest" | "concat"; query: string; metric?: TrigramMetric; threshold?: number }
+  | { fields: Array<{ field: string; weight: number }>; query: string; metric?: TrigramMetric; threshold?: number };
+
+/**
+ * Build a pg_trgm function expression for a raw SQL field expression.
+ * $1 is always the query string parameter.
+ */
+function trigramFnRaw(fieldExpr: string, metric?: TrigramMetric): string {
+  switch (metric) {
+    case "wordSimilarity":      return \`word_similarity($1, \${fieldExpr})\`;
+    case "strictWordSimilarity": return \`strict_word_similarity($1, \${fieldExpr})\`;
+    default:                    return \`similarity(\${fieldExpr}, $1)\`;
+  }
+}
+
+/** Build the full pg_trgm SQL expression for the given trigram param. */
+function getTrigramFnExpr(trigram: TrigramParam): string {
+  if ("field" in trigram) {
+    return trigramFnRaw(\`"\${trigram.field}"\`, trigram.metric);
+  }
+
+  const { fields, metric } = trigram;
+
+  // Weighted: fields is Array<{ field, weight }>
+  if (fields.length > 0 && typeof fields[0] === "object" && "weight" in fields[0]) {
+    const wfields = fields as Array<{ field: string; weight: number }>;
+    const totalWeight = wfields.reduce((sum, f) => sum + f.weight, 0);
+    const terms = wfields.map(f => \`\${trigramFnRaw(\`"\${f.field}"\`, metric)} * \${f.weight}\`).join(" + ");
+    return \`(\${terms}) / \${totalWeight}\`;
+  }
+
+  const sfields = fields as string[];
+  const strategy = (trigram as Extract<TrigramParam, { fields: string[] }>).strategy ?? "greatest";
+
+  if (strategy === "concat") {
+    const concatExpr = sfields.map(f => \`"\${f}"\`).join(\` || ' ' || \`);
+    return trigramFnRaw(concatExpr, metric);
+  }
+
+  // greatest (default)
+  return \`GREATEST(\${sfields.map(f => trigramFnRaw(\`"\${f}"\`, metric)).join(", ")})\`;
+}
+
 /** Builds a SQL ORDER BY clause from parallel cols/dirs arrays. Returns "" when cols is empty. */
 function buildOrderBySQL(cols: string[], dirs: ("asc" | "desc")[]): string {
   if (cols.length === 0) return "";
@@ -6248,7 +6350,7 @@ function buildOrderBySQL(cols: string[], dirs: ("asc" | "desc")[]): string {
 }
 
 /**
- * LIST operation - Get multiple records with optional filters and vector search
+ * LIST operation - Get multiple records with optional filters, vector search, and trigram similarity search
  */
 export async function listRecords(
   ctx: OperationContext,
@@ -6266,10 +6368,11 @@ export async function listRecords(
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };
+    trigram?: TrigramParam;
   }
 ): Promise<{ data?: any; total?: number; limit?: number; offset?: number; hasMore?: boolean; error?: string; issues?: any; needsIncludes?: boolean; includeSpec?: any; status: number }> {
   try {
-    const { where: whereClause, limit = 50, offset = 0, include, orderBy, order, vector, distinctOn } = params;
+    const { where: whereClause, limit = 50, offset = 0, include, orderBy, order, vector, trigram, distinctOn } = params;
 
     // DISTINCT ON support
     const distinctCols: string[] | null = distinctOn ? (Array.isArray(distinctOn) ? distinctOn : [distinctOn]) : null;
@@ -6280,20 +6383,28 @@ export async function listRecords(
 
     // Auto-detect subquery form: needed when distinctOn is set AND the caller wants to order
     // by a column outside of distinctOn (inline DISTINCT ON can't satisfy that without silently
-    // overriding the requested ordering). Vector search always stays inline.
+    // overriding the requested ordering). Vector/trigram search always stays inline.
     const useSubquery: boolean =
       distinctCols !== null &&
       !vector &&
+      !trigram &&
       userOrderCols.some(col => !distinctCols.includes(col));
 
     // Get distance operator if vector search
     const distanceOp = vector ? getVectorDistanceOperator(vector.metric) : "";
 
-    // Add vector to params array if present
-    const queryParams: any[] = vector ? [JSON.stringify(vector.query)] : [];
+    // Get trigram similarity SQL expression (pg_trgm). $1 is always the query string.
+    const trigramFnExpr = trigram ? getTrigramFnExpr(trigram) : "";
+
+    // Add vector or trigram query as $1 if present (mutually exclusive)
+    const queryParams: any[] = vector
+      ? [JSON.stringify(vector.query)]
+      : trigram
+      ? [trigram.query]
+      : [];
 
-    // Build WHERE clause for SELECT/UPDATE queries (with vector as $1 if present)
-    let paramIndex = vector ? 2 : 1;
+    // Build WHERE clause for SELECT/UPDATE queries (with vector/trigram as $1 if present)
+    let paramIndex = vector || trigram ? 2 : 1;
     const whereParts: string[] = [];
     let whereParams: any[] = [];
 
@@ -6317,28 +6428,38 @@ export async function listRecords(
       whereParts.push(\`("\${vector.field}" \${distanceOp} ($1)::vector) < \${vector.maxDistance}\`);
     }
 
+    // Add trigram threshold filter if specified (inlined as literal — it's a float, safe)
+    if (trigram?.threshold !== undefined) {
+      whereParts.push(\`\${trigramFnExpr} >= \${trigram.threshold}\`);
+    }
+
     const whereSQL = whereParts.length > 0 ? \`WHERE \${whereParts.join(" AND ")}\` : "";
 
     // Build WHERE clause for COUNT query (may need different param indices)
     let countWhereSQL = whereSQL;
     let countParams = whereParams;
 
-    if (vector && vector.maxDistance === undefined && whereParams.length > 0) {
-      // COUNT query doesn't use vector, so rebuild WHERE without vector offset
+    // When a $1 query param exists (vector/trigram) but has NO threshold filter, the COUNT query
+    // must not reference $1 since it's only needed in SELECT/ORDER BY. Rebuild WHERE from scratch
+    // starting at $1. When a threshold IS set, $1 appears in the WHERE condition so keep it.
+    const hasQueryParam = !!(vector || trigram);
+    const hasThreshold = vector?.maxDistance !== undefined || trigram?.threshold !== undefined;
+
+    if (hasQueryParam && !hasThreshold && whereParams.length > 0) {
       const countWhereParts: string[] = [];
       if (ctx.softDeleteColumn) {
         countWhereParts.push(\`"\${ctx.softDeleteColumn}" IS NULL\`);
       }
       if (whereClause) {
-        const result = buildWhereClause(whereClause, 1); // Start at $1 for count
+        const result = buildWhereClause(whereClause, 1); // Start at $1, no query-param offset
         if (result.sql) {
           countWhereParts.push(result.sql);
           countParams = result.params;
         }
       }
       countWhereSQL = countWhereParts.length > 0 ? \`WHERE \${countWhereParts.join(" AND ")}\` : "";
-    } else if (vector?.maxDistance !== undefined) {
-      // COUNT query includes vector for maxDistance filter
+    } else if (hasQueryParam && hasThreshold) {
+      // $1 appears in WHERE threshold condition — COUNT needs the full params
       countParams = [...queryParams, ...whereParams];
     }
 
@@ -6347,6 +6468,8 @@ export async function listRecords(
     const baseColumns = buildColumnList(ctx.select, ctx.exclude, ctx.allColumnNames);
     const selectClause = vector
       ? \`\${_distinctOnPrefix}\${baseColumns}, ("\${vector.field}" \${distanceOp} ($1)::vector) AS _distance\`
+      : trigram
+      ? \`\${_distinctOnPrefix}\${baseColumns}, \${trigramFnExpr} AS _similarity\`
       : \`\${_distinctOnPrefix}\${baseColumns}\`;
 
     // Build ORDER BY clause
@@ -6358,6 +6481,9 @@ export async function listRecords(
     if (vector) {
       // Vector search always orders by distance; DISTINCT ON + vector stays inline
       orderBySQL = \`ORDER BY "\${vector.field}" \${distanceOp} ($1)::vector\`;
+    } else if (trigram) {
+      // Trigram search orders by similarity score descending
+      orderBySQL = \`ORDER BY _similarity DESC\`;
     } else if (useSubquery) {
       // Subquery form: outer query gets the user's full ORDER BY.
       // Inner query only needs to satisfy PG's DISTINCT ON prefix requirement (built at query assembly).

package/dist/index.js

@@ -2267,6 +2267,7 @@ function emitHonoRoutes(table, _graph, opts) {
   const fileTableName = table.name;
   const Type = pascal(table.name);
   const hasVectorColumns = table.columns.some((c) => isVectorType(c.pgType));
+  const trigramMetricZod = `z.enum(["similarity", "wordSimilarity", "strictWordSimilarity"]).optional()`;
   const vectorColumns = table.columns.filter((c) => isVectorType(c.pgType)).map((c) => c.name);
   const jsonbColumns = table.columns.filter((c) => isJsonbType(c.pgType)).map((c) => c.name);
   const rawPk = table.pk;
@@ -2332,7 +2333,28 @@ const listSchema = z.object({
     query: z.array(z.number()),
     metric: z.enum(["cosine", "l2", "inner"]).optional(),
     maxDistance: z.number().optional()
-  }).optional()` : ""}
+  }).optional(),` : ""}
+  trigram: z.union([
+    z.object({
+      field: z.string(),
+      query: z.string(),
+      metric: ${trigramMetricZod},
+      threshold: z.number().min(0).max(1).optional()
+    }),
+    z.object({
+      fields: z.array(z.string()).min(1),
+      strategy: z.enum(["greatest", "concat"]).optional(),
+      query: z.string(),
+      metric: ${trigramMetricZod},
+      threshold: z.number().min(0).max(1).optional()
+    }),
+    z.object({
+      fields: z.array(z.object({ field: z.string(), weight: z.number().positive() })).min(1),
+      query: z.string(),
+      metric: ${trigramMetricZod},
+      threshold: z.number().min(0).max(1).optional()
+    })
+  ]).optional()
 }).strict().refine(
   (data) => !(data.select && data.exclude),
   { message: "Cannot specify both 'select' and 'exclude' parameters" }
@@ -2600,6 +2622,7 @@ function analyzeIncludeSpec(includeSpec) {
 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));
   if (process.env.SDK_DEBUG) {
@@ -3003,10 +3026,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<Partial<Select${Type}<TJsonb>>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<Partial<Select${Type}<TJsonb>> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   /**
    * List ${table.name} records with field exclusion
    * @param params - Query parameters with exclude
@@ -3024,10 +3048,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<Partial<Select${Type}<TJsonb>>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<Partial<Select${Type}<TJsonb>> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   /**
    * List ${table.name} records with pagination and filtering
    * @param params - Query parameters
@@ -3056,10 +3081,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   async list<TJsonb extends Partial<Select${Type}> = {}>(params?: {
     include?: ${Type}IncludeSpec;
     select?: string[];
@@ -3073,11 +3099,12 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
   }): Promise<PaginatedResponse<Select${Type}<TJsonb> | Partial<Select${Type}<TJsonb>>>> {
-    return this.post<PaginatedResponse<Select${Type}<TJsonb>${hasVectorColumns ? " & { _distance?: number }" : ""}>>(\`\${this.resource}/list\`, params ?? {});
+    return this.post<PaginatedResponse<Select${Type}<TJsonb> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>(\`\${this.resource}/list\`, params ?? {});
   }` : `  /**
    * List ${table.name} records with field selection
    * @param params - Query parameters with select
@@ -3095,10 +3122,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<Partial<Select${Type}>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<Partial<Select${Type}> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   /**
    * List ${table.name} records with field exclusion
    * @param params - Query parameters with exclude
@@ -3116,10 +3144,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<Partial<Select${Type}>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<Partial<Select${Type}> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   /**
    * List ${table.name} records with pagination and filtering
    * @param params - Query parameters
@@ -3142,10 +3171,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
-  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude> & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   async list(params?: {
     include?: ${Type}IncludeSpec;
     select?: string[];
@@ -3159,11 +3189,12 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: ${trigramParamType};
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
     distinctOn?: string | string[];
   }): Promise<PaginatedResponse<Select${Type} | Partial<Select${Type}>>> {
-    return this.post<PaginatedResponse<Select${Type}${hasVectorColumns ? " & { _distance?: number }" : ""}>>(\`\${this.resource}/list\`, params ?? {});
+    return this.post<PaginatedResponse<Select${Type} & { _similarity?: number }${hasVectorColumns ? " & { _distance?: number }" : ""}>>(\`\${this.resource}/list\`, params ?? {});
   }`}
 
 ${hasJsonbColumns ? `  /**
@@ -4331,6 +4362,12 @@ export type WhereOperator<T> = {
   $like?: T extends string ? string : never;
   /** Case-insensitive LIKE (strings only) */
   $ilike?: T extends string ? string : never;
+  /** Trigram similarity match - "col" % value (pg_trgm required, uses similarity_threshold GUC) */
+  $similarity?: T extends string ? string : never;
+  /** Word trigram similarity match - value <% "col" (pg_trgm required) */
+  $wordSimilarity?: T extends string ? string : never;
+  /** Strict word trigram similarity match - value <<% "col" (pg_trgm required) */
+  $strictWordSimilarity?: T extends string ? string : never;
   /** IS NULL */
   $is?: null;
   /** IS NOT NULL */
@@ -4947,7 +4984,7 @@ export async function createRecord(
 
     const preparedVals = vals.map((v, i) =>
       v !== null && v !== undefined && typeof v === 'object' &&
-      (ctx.jsonbColumns?.includes(cols[i]) || ctx.vectorColumns?.includes(cols[i]))
+      (ctx.jsonbColumns?.includes(cols[i]!) || ctx.vectorColumns?.includes(cols[i]!))
         ? JSON.stringify(v)
         : v
     );
@@ -5107,6 +5144,24 @@ function buildWhereClause(
             whereParams.push(opValue);
             paramIndex++;
             break;
+          case '$similarity':
+            // pg_trgm: boolean similarity operator (respects similarity_threshold GUC)
+            whereParts.push(\`"\${key}" % $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$wordSimilarity':
+            // pg_trgm: word similarity operator (value <% col)
+            whereParts.push(\`$\${paramIndex} <% "\${key}"\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$strictWordSimilarity':
+            // pg_trgm: strict word similarity operator (value <<% col)
+            whereParts.push(\`$\${paramIndex} <<% "\${key}"\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
           case '$is':
             if (opValue === null) {
               whereParts.push(\`"\${key}" IS NULL\`);
@@ -5280,6 +5335,53 @@ function getVectorDistanceOperator(metric?: string): string {
   }
 }
 
+export type TrigramMetric = "similarity" | "wordSimilarity" | "strictWordSimilarity";
+
+export type TrigramParam =
+  | { field: string; query: string; metric?: TrigramMetric; threshold?: number }
+  | { fields: string[]; strategy?: "greatest" | "concat"; query: string; metric?: TrigramMetric; threshold?: number }
+  | { fields: Array<{ field: string; weight: number }>; query: string; metric?: TrigramMetric; threshold?: number };
+
+/**
+ * Build a pg_trgm function expression for a raw SQL field expression.
+ * $1 is always the query string parameter.
+ */
+function trigramFnRaw(fieldExpr: string, metric?: TrigramMetric): string {
+  switch (metric) {
+    case "wordSimilarity":      return \`word_similarity($1, \${fieldExpr})\`;
+    case "strictWordSimilarity": return \`strict_word_similarity($1, \${fieldExpr})\`;
+    default:                    return \`similarity(\${fieldExpr}, $1)\`;
+  }
+}
+
+/** Build the full pg_trgm SQL expression for the given trigram param. */
+function getTrigramFnExpr(trigram: TrigramParam): string {
+  if ("field" in trigram) {
+    return trigramFnRaw(\`"\${trigram.field}"\`, trigram.metric);
+  }
+
+  const { fields, metric } = trigram;
+
+  // Weighted: fields is Array<{ field, weight }>
+  if (fields.length > 0 && typeof fields[0] === "object" && "weight" in fields[0]) {
+    const wfields = fields as Array<{ field: string; weight: number }>;
+    const totalWeight = wfields.reduce((sum, f) => sum + f.weight, 0);
+    const terms = wfields.map(f => \`\${trigramFnRaw(\`"\${f.field}"\`, metric)} * \${f.weight}\`).join(" + ");
+    return \`(\${terms}) / \${totalWeight}\`;
+  }
+
+  const sfields = fields as string[];
+  const strategy = (trigram as Extract<TrigramParam, { fields: string[] }>).strategy ?? "greatest";
+
+  if (strategy === "concat") {
+    const concatExpr = sfields.map(f => \`"\${f}"\`).join(\` || ' ' || \`);
+    return trigramFnRaw(concatExpr, metric);
+  }
+
+  // greatest (default)
+  return \`GREATEST(\${sfields.map(f => trigramFnRaw(\`"\${f}"\`, metric)).join(", ")})\`;
+}
+
 /** Builds a SQL ORDER BY clause from parallel cols/dirs arrays. Returns "" when cols is empty. */
 function buildOrderBySQL(cols: string[], dirs: ("asc" | "desc")[]): string {
   if (cols.length === 0) return "";
@@ -5287,7 +5389,7 @@ function buildOrderBySQL(cols: string[], dirs: ("asc" | "desc")[]): string {
 }
 
 /**
- * LIST operation - Get multiple records with optional filters and vector search
+ * LIST operation - Get multiple records with optional filters, vector search, and trigram similarity search
  */
 export async function listRecords(
   ctx: OperationContext,
@@ -5305,10 +5407,11 @@ export async function listRecords(
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };
+    trigram?: TrigramParam;
   }
 ): Promise<{ data?: any; total?: number; limit?: number; offset?: number; hasMore?: boolean; error?: string; issues?: any; needsIncludes?: boolean; includeSpec?: any; status: number }> {
   try {
-    const { where: whereClause, limit = 50, offset = 0, include, orderBy, order, vector, distinctOn } = params;
+    const { where: whereClause, limit = 50, offset = 0, include, orderBy, order, vector, trigram, distinctOn } = params;
 
     // DISTINCT ON support
     const distinctCols: string[] | null = distinctOn ? (Array.isArray(distinctOn) ? distinctOn : [distinctOn]) : null;
@@ -5319,20 +5422,28 @@ export async function listRecords(
 
     // Auto-detect subquery form: needed when distinctOn is set AND the caller wants to order
     // by a column outside of distinctOn (inline DISTINCT ON can't satisfy that without silently
-    // overriding the requested ordering). Vector search always stays inline.
+    // overriding the requested ordering). Vector/trigram search always stays inline.
     const useSubquery: boolean =
       distinctCols !== null &&
       !vector &&
+      !trigram &&
       userOrderCols.some(col => !distinctCols.includes(col));
 
     // Get distance operator if vector search
     const distanceOp = vector ? getVectorDistanceOperator(vector.metric) : "";
 
-    // Add vector to params array if present
-    const queryParams: any[] = vector ? [JSON.stringify(vector.query)] : [];
+    // Get trigram similarity SQL expression (pg_trgm). $1 is always the query string.
+    const trigramFnExpr = trigram ? getTrigramFnExpr(trigram) : "";
+
+    // Add vector or trigram query as $1 if present (mutually exclusive)
+    const queryParams: any[] = vector
+      ? [JSON.stringify(vector.query)]
+      : trigram
+      ? [trigram.query]
+      : [];
 
-    // Build WHERE clause for SELECT/UPDATE queries (with vector as $1 if present)
-    let paramIndex = vector ? 2 : 1;
+    // Build WHERE clause for SELECT/UPDATE queries (with vector/trigram as $1 if present)
+    let paramIndex = vector || trigram ? 2 : 1;
     const whereParts: string[] = [];
     let whereParams: any[] = [];
 
@@ -5356,28 +5467,38 @@ export async function listRecords(
       whereParts.push(\`("\${vector.field}" \${distanceOp} ($1)::vector) < \${vector.maxDistance}\`);
     }
 
+    // Add trigram threshold filter if specified (inlined as literal — it's a float, safe)
+    if (trigram?.threshold !== undefined) {
+      whereParts.push(\`\${trigramFnExpr} >= \${trigram.threshold}\`);
+    }
+
     const whereSQL = whereParts.length > 0 ? \`WHERE \${whereParts.join(" AND ")}\` : "";
 
     // Build WHERE clause for COUNT query (may need different param indices)
     let countWhereSQL = whereSQL;
     let countParams = whereParams;
 
-    if (vector && vector.maxDistance === undefined && whereParams.length > 0) {
-      // COUNT query doesn't use vector, so rebuild WHERE without vector offset
+    // When a $1 query param exists (vector/trigram) but has NO threshold filter, the COUNT query
+    // must not reference $1 since it's only needed in SELECT/ORDER BY. Rebuild WHERE from scratch
+    // starting at $1. When a threshold IS set, $1 appears in the WHERE condition so keep it.
+    const hasQueryParam = !!(vector || trigram);
+    const hasThreshold = vector?.maxDistance !== undefined || trigram?.threshold !== undefined;
+
+    if (hasQueryParam && !hasThreshold && whereParams.length > 0) {
       const countWhereParts: string[] = [];
       if (ctx.softDeleteColumn) {
         countWhereParts.push(\`"\${ctx.softDeleteColumn}" IS NULL\`);
       }
       if (whereClause) {
-        const result = buildWhereClause(whereClause, 1); // Start at $1 for count
+        const result = buildWhereClause(whereClause, 1); // Start at $1, no query-param offset
         if (result.sql) {
           countWhereParts.push(result.sql);
           countParams = result.params;
         }
       }
       countWhereSQL = countWhereParts.length > 0 ? \`WHERE \${countWhereParts.join(" AND ")}\` : "";
-    } else if (vector?.maxDistance !== undefined) {
-      // COUNT query includes vector for maxDistance filter
+    } else if (hasQueryParam && hasThreshold) {
+      // $1 appears in WHERE threshold condition — COUNT needs the full params
       countParams = [...queryParams, ...whereParams];
     }
 
@@ -5386,6 +5507,8 @@ export async function listRecords(
     const baseColumns = buildColumnList(ctx.select, ctx.exclude, ctx.allColumnNames);
     const selectClause = vector
       ? \`\${_distinctOnPrefix}\${baseColumns}, ("\${vector.field}" \${distanceOp} ($1)::vector) AS _distance\`
+      : trigram
+      ? \`\${_distinctOnPrefix}\${baseColumns}, \${trigramFnExpr} AS _similarity\`
       : \`\${_distinctOnPrefix}\${baseColumns}\`;
 
     // Build ORDER BY clause
@@ -5397,6 +5520,9 @@ export async function listRecords(
     if (vector) {
       // Vector search always orders by distance; DISTINCT ON + vector stays inline
       orderBySQL = \`ORDER BY "\${vector.field}" \${distanceOp} ($1)::vector\`;
+    } else if (trigram) {
+      // Trigram search orders by similarity score descending
+      orderBySQL = \`ORDER BY _similarity DESC\`;
     } else if (useSubquery) {
       // Subquery form: outer query gets the user's full ORDER BY.
       // Inner query only needs to satisfy PG's DISTINCT ON prefix requirement (built at query assembly).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.18.19",
+  "version": "0.18.21",
   "description": "Generate a typed server/client SDK from a Postgres schema (includes, Zod, Hono).",
   "type": "module",
   "bin": {
@@ -22,7 +22,7 @@
   },
   "scripts": {
     "build": "bun build src/cli.ts src/index.ts --outdir dist --target node --format esm --external=pg --external=zod --external=hono --external=prompts --external=node:* && tsc -p tsconfig.build.json --emitDeclarationOnly",
-    "test": "bun test:write-files && bun test:init && bun test:gen && bun test test/test-where-clause.test.ts && bun test test/test-where-or-and.test.ts && bun test test/test-nested-include-options.test.ts && bun test test/test-include-methods-with-options.test.ts && bun test:gen-with-tests && bun test:pull && bun test:enums && bun test:typecheck && bun test:drizzle-e2e && bun test test/test-numeric-mode-integration.test.ts && bun test test/test-jsonb-array-serialization.test.ts",
+    "test": "bun test:write-files && bun test:init && bun test:gen && bun test test/test-where-clause.test.ts && bun test test/test-where-or-and.test.ts && bun test test/test-nested-include-options.test.ts && bun test test/test-include-methods-with-options.test.ts && bun test:gen-with-tests && bun test:pull && bun test:enums && bun test:typecheck && bun test:drizzle-e2e && bun test test/test-numeric-mode-integration.test.ts && bun test test/test-jsonb-array-serialization.test.ts && bun test test/test-trigram-search.test.ts",
     "test:write-files": "bun test/test-write-files-if-changed.ts",
     "test:init": "bun test/test-init.ts",
     "test:gen": "bun test/test-gen.ts",