postgresdk 0.18.18 → 0.18.20

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,59 @@ 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
+  }
+});
+```
+
+**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

@@ -3293,7 +3293,13 @@ const listSchema = z.object({
     query: z.array(z.number()),
     metric: z.enum(["cosine", "l2", "inner"]).optional(),
     maxDistance: z.number().optional()
-  }).optional()` : ""}
+  }).optional(),` : ""}
+  trigram: z.object({
+    field: z.string(),
+    query: z.string(),
+    metric: z.enum(["similarity", "wordSimilarity", "strictWordSimilarity"]).optional(),
+    threshold: z.number().min(0).max(1).optional()
+  }).optional()
 }).strict().refine(
   (data) => !(data.select && data.exclude),
   { message: "Cannot specify both 'select' and 'exclude' parameters" }
@@ -3964,10 +3970,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +3992,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +4025,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +4043,12 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +4066,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +4088,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +4115,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +4133,12 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +5306,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 */
@@ -6068,6 +6088,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\`);
@@ -6242,7 +6280,29 @@ function getVectorDistanceOperator(metric?: string): string {
 }
 
 /**
- * LIST operation - Get multiple records with optional filters and vector search
+ * Build the pg_trgm SQL function expression for a given field and metric.
+ * $1 is always the query string parameter.
+ */
+function getTrigramFnExpr(field: string, metric?: string): string {
+  switch (metric) {
+    case "wordSimilarity":
+      return \`word_similarity($1, "\${field}")\`;
+    case "strictWordSimilarity":
+      return \`strict_word_similarity($1, "\${field}")\`;
+    case "similarity":
+    default:
+      return \`similarity("\${field}", $1)\`;
+  }
+}
+
+/** 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 "";
+  return \`ORDER BY \${cols.map((c, i) => \`"\${c}" \${(dirs[i] ?? "asc").toUpperCase()}\`).join(", ")}\`;
+}
+
+/**
+ * LIST operation - Get multiple records with optional filters, vector search, and trigram similarity search
  */
 export async function listRecords(
   ctx: OperationContext,
@@ -6260,23 +6320,48 @@ export async function listRecords(
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };
+    trigram?: {
+      field: string;
+      query: string;
+      metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity";
+      threshold?: number;
+    };
   }
 ): 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;
     const _distinctOnColsSQL = distinctCols ? distinctCols.map(c => '"' + c + '"').join(', ') : '';
 
+    // Pre-compute user order cols (reused in ORDER BY block and useSubquery check)
+    const userOrderCols: string[] = orderBy ? (Array.isArray(orderBy) ? orderBy : [orderBy]) : [];
+
+    // 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/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.field, trigram.metric) : "";
 
-    // Build WHERE clause for SELECT/UPDATE queries (with vector as $1 if present)
-    let paramIndex = vector ? 2 : 1;
+    // 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/trigram as $1 if present)
+    let paramIndex = vector || trigram ? 2 : 1;
     const whereParts: string[] = [];
     let whereParams: any[] = [];
 
@@ -6300,28 +6385,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];
     }
 
@@ -6330,45 +6425,44 @@ 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
     let orderBySQL = "";
+    const userDirs: ("asc" | "desc")[] = userOrderCols.length > 0
+      ? (Array.isArray(order) ? order : (order ? Array(userOrderCols.length).fill(order) : Array(userOrderCols.length).fill("asc")))
+      : [];
+
     if (vector) {
-      // For vector search, always order by distance
+      // Vector search always orders by distance; DISTINCT ON + vector stays inline
       orderBySQL = \`ORDER BY "\${vector.field}" \${distanceOp} ($1)::vector\`;
-    } else {
-      const userCols = orderBy ? (Array.isArray(orderBy) ? orderBy : [orderBy]) : [];
-      const userDirs: ("asc" | "desc")[] = orderBy
-        ? (Array.isArray(order) ? order : (order ? Array(userCols.length).fill(order) : Array(userCols.length).fill("asc")))
-        : [];
-
+    } 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).
+      orderBySQL = buildOrderBySQL(userOrderCols, userDirs);
+    } else if (distinctCols) {
+      // Inline DISTINCT ON: prepend distinctCols as the leftmost ORDER BY prefix (PG requirement)
       const finalCols: string[] = [];
-      const finalDirs: string[] = [];
-
-      if (distinctCols) {
-        // DISTINCT ON requires its columns to be the leftmost ORDER BY prefix
-        for (const col of distinctCols) {
-          const userIdx = userCols.indexOf(col);
-          finalCols.push(col);
-          finalDirs.push(userIdx >= 0 ? (userDirs[userIdx] || "asc") : "asc");
-        }
-        // Append remaining user-specified cols not already covered by distinctOn
-        for (let i = 0; i < userCols.length; i++) {
-          if (!distinctCols.includes(userCols[i]!)) {
-            finalCols.push(userCols[i]!);
-            finalDirs.push(userDirs[i] || "asc");
-          }
-        }
-      } else {
-        finalCols.push(...userCols);
-        finalDirs.push(...userDirs.map(d => d || "asc"));
+      const finalDirs: ("asc" | "desc")[] = [];
+      for (const col of distinctCols) {
+        const userIdx = userOrderCols.indexOf(col);
+        finalCols.push(col);
+        finalDirs.push(userIdx >= 0 ? (userDirs[userIdx] ?? "asc") : "asc");
       }
-
-      if (finalCols.length > 0) {
-        const orderParts = finalCols.map((c, i) => \`"\${c}" \${finalDirs[i]!.toUpperCase()}\`);
-        orderBySQL = \`ORDER BY \${orderParts.join(", ")}\`;
+      for (let i = 0; i < userOrderCols.length; i++) {
+        if (!distinctCols.includes(userOrderCols[i]!)) {
+          finalCols.push(userOrderCols[i]!);
+          finalDirs.push(userDirs[i] ?? "asc");
+        }
       }
+      orderBySQL = buildOrderBySQL(finalCols, finalDirs);
+    } else {
+      orderBySQL = buildOrderBySQL(userOrderCols, userDirs);
     }
 
     // Add limit and offset params
@@ -6385,7 +6479,15 @@ export async function listRecords(
     const total = parseInt(countResult.rows[0].count, 10);
 
     // Get paginated data
-    const text = \`SELECT \${selectClause} FROM "\${ctx.table}" \${whereSQL} \${orderBySQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
+    let text: string;
+    if (useSubquery) {
+      // Inner query: DISTINCT ON with only the distinctCols ORDER BY prefix (PG requirement).
+      // Outer query: free ORDER BY from the user's full orderBy list, plus LIMIT/OFFSET.
+      const innerQuery = \`SELECT DISTINCT ON (\${_distinctOnColsSQL}) \${baseColumns} FROM "\${ctx.table}" \${whereSQL} ORDER BY \${_distinctOnColsSQL}\`;
+      text = \`SELECT * FROM (\${innerQuery}) __distinct \${orderBySQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
+    } else {
+      text = \`SELECT \${selectClause} FROM "\${ctx.table}" \${whereSQL} \${orderBySQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
+    }
     log.debug(\`LIST \${ctx.table} SQL:\`, text, "params:", allParams);
 
     const { rows } = await ctx.pg.query(text, allParams);

package/dist/index.js

@@ -2332,7 +2332,13 @@ const listSchema = z.object({
     query: z.array(z.number()),
     metric: z.enum(["cosine", "l2", "inner"]).optional(),
     maxDistance: z.number().optional()
-  }).optional()` : ""}
+  }).optional(),` : ""}
+  trigram: z.object({
+    field: z.string(),
+    query: z.string(),
+    metric: z.enum(["similarity", "wordSimilarity", "strictWordSimilarity"]).optional(),
+    threshold: z.number().min(0).max(1).optional()
+  }).optional()
 }).strict().refine(
   (data) => !(data.select && data.exclude),
   { message: "Cannot specify both 'select' and 'exclude' parameters" }
@@ -3003,10 +3009,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +3031,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +3064,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +3082,12 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +3105,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +3127,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +3154,11 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +3172,12 @@ ${hasJsonbColumns ? `  /**
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };` : ""}
+    trigram?: { field: string; query: string; metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity"; threshold?: number };
     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 +4345,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 */
@@ -5107,6 +5127,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\`);
@@ -5281,7 +5319,29 @@ function getVectorDistanceOperator(metric?: string): string {
 }
 
 /**
- * LIST operation - Get multiple records with optional filters and vector search
+ * Build the pg_trgm SQL function expression for a given field and metric.
+ * $1 is always the query string parameter.
+ */
+function getTrigramFnExpr(field: string, metric?: string): string {
+  switch (metric) {
+    case "wordSimilarity":
+      return \`word_similarity($1, "\${field}")\`;
+    case "strictWordSimilarity":
+      return \`strict_word_similarity($1, "\${field}")\`;
+    case "similarity":
+    default:
+      return \`similarity("\${field}", $1)\`;
+  }
+}
+
+/** 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 "";
+  return \`ORDER BY \${cols.map((c, i) => \`"\${c}" \${(dirs[i] ?? "asc").toUpperCase()}\`).join(", ")}\`;
+}
+
+/**
+ * LIST operation - Get multiple records with optional filters, vector search, and trigram similarity search
  */
 export async function listRecords(
   ctx: OperationContext,
@@ -5299,23 +5359,48 @@ export async function listRecords(
       metric?: "cosine" | "l2" | "inner";
       maxDistance?: number;
     };
+    trigram?: {
+      field: string;
+      query: string;
+      metric?: "similarity" | "wordSimilarity" | "strictWordSimilarity";
+      threshold?: number;
+    };
   }
 ): 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;
     const _distinctOnColsSQL = distinctCols ? distinctCols.map(c => '"' + c + '"').join(', ') : '';
 
+    // Pre-compute user order cols (reused in ORDER BY block and useSubquery check)
+    const userOrderCols: string[] = orderBy ? (Array.isArray(orderBy) ? orderBy : [orderBy]) : [];
+
+    // 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/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.field, trigram.metric) : "";
 
-    // Build WHERE clause for SELECT/UPDATE queries (with vector as $1 if present)
-    let paramIndex = vector ? 2 : 1;
+    // 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/trigram as $1 if present)
+    let paramIndex = vector || trigram ? 2 : 1;
     const whereParts: string[] = [];
     let whereParams: any[] = [];
 
@@ -5339,28 +5424,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];
     }
 
@@ -5369,45 +5464,44 @@ 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
     let orderBySQL = "";
+    const userDirs: ("asc" | "desc")[] = userOrderCols.length > 0
+      ? (Array.isArray(order) ? order : (order ? Array(userOrderCols.length).fill(order) : Array(userOrderCols.length).fill("asc")))
+      : [];
+
     if (vector) {
-      // For vector search, always order by distance
+      // Vector search always orders by distance; DISTINCT ON + vector stays inline
       orderBySQL = \`ORDER BY "\${vector.field}" \${distanceOp} ($1)::vector\`;
-    } else {
-      const userCols = orderBy ? (Array.isArray(orderBy) ? orderBy : [orderBy]) : [];
-      const userDirs: ("asc" | "desc")[] = orderBy
-        ? (Array.isArray(order) ? order : (order ? Array(userCols.length).fill(order) : Array(userCols.length).fill("asc")))
-        : [];
-
+    } 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).
+      orderBySQL = buildOrderBySQL(userOrderCols, userDirs);
+    } else if (distinctCols) {
+      // Inline DISTINCT ON: prepend distinctCols as the leftmost ORDER BY prefix (PG requirement)
       const finalCols: string[] = [];
-      const finalDirs: string[] = [];
-
-      if (distinctCols) {
-        // DISTINCT ON requires its columns to be the leftmost ORDER BY prefix
-        for (const col of distinctCols) {
-          const userIdx = userCols.indexOf(col);
-          finalCols.push(col);
-          finalDirs.push(userIdx >= 0 ? (userDirs[userIdx] || "asc") : "asc");
-        }
-        // Append remaining user-specified cols not already covered by distinctOn
-        for (let i = 0; i < userCols.length; i++) {
-          if (!distinctCols.includes(userCols[i]!)) {
-            finalCols.push(userCols[i]!);
-            finalDirs.push(userDirs[i] || "asc");
-          }
-        }
-      } else {
-        finalCols.push(...userCols);
-        finalDirs.push(...userDirs.map(d => d || "asc"));
+      const finalDirs: ("asc" | "desc")[] = [];
+      for (const col of distinctCols) {
+        const userIdx = userOrderCols.indexOf(col);
+        finalCols.push(col);
+        finalDirs.push(userIdx >= 0 ? (userDirs[userIdx] ?? "asc") : "asc");
       }
-
-      if (finalCols.length > 0) {
-        const orderParts = finalCols.map((c, i) => \`"\${c}" \${finalDirs[i]!.toUpperCase()}\`);
-        orderBySQL = \`ORDER BY \${orderParts.join(", ")}\`;
+      for (let i = 0; i < userOrderCols.length; i++) {
+        if (!distinctCols.includes(userOrderCols[i]!)) {
+          finalCols.push(userOrderCols[i]!);
+          finalDirs.push(userDirs[i] ?? "asc");
+        }
       }
+      orderBySQL = buildOrderBySQL(finalCols, finalDirs);
+    } else {
+      orderBySQL = buildOrderBySQL(userOrderCols, userDirs);
     }
 
     // Add limit and offset params
@@ -5424,7 +5518,15 @@ export async function listRecords(
     const total = parseInt(countResult.rows[0].count, 10);
 
     // Get paginated data
-    const text = \`SELECT \${selectClause} FROM "\${ctx.table}" \${whereSQL} \${orderBySQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
+    let text: string;
+    if (useSubquery) {
+      // Inner query: DISTINCT ON with only the distinctCols ORDER BY prefix (PG requirement).
+      // Outer query: free ORDER BY from the user's full orderBy list, plus LIMIT/OFFSET.
+      const innerQuery = \`SELECT DISTINCT ON (\${_distinctOnColsSQL}) \${baseColumns} FROM "\${ctx.table}" \${whereSQL} ORDER BY \${_distinctOnColsSQL}\`;
+      text = \`SELECT * FROM (\${innerQuery}) __distinct \${orderBySQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
+    } else {
+      text = \`SELECT \${selectClause} FROM "\${ctx.table}" \${whereSQL} \${orderBySQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
+    }
     log.debug(\`LIST \${ctx.table} SQL:\`, text, "params:", allParams);
 
     const { rows } = await ctx.pg.query(text, allParams);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.18.18",
+  "version": "0.18.20",
   "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",