postgresdk 0.19.3 → 0.19.5

package/README.md

@@ -154,6 +154,7 @@ export default {
     },
   },
   numericMode: "auto",                 // "auto" | "number" | "string" - How to type numeric columns
+  maxLimit: 1000,                      // Max allowed `limit` value (0 = no cap)
   includeMethodsDepth: 2,              // Max depth for nested includes
   dateType: "date",                    // "date" | "string" - How to handle timestamps
   serverFramework: "hono",             // Currently only hono is supported
@@ -715,15 +716,15 @@ const result = await sdk.users.list({
 // Access results
 result.data;       // User[] - array of records
 result.total;      // number - total matching records
-result.limit;      // number - page size used
+result.limit;      // number | undefined - page size used (absent when no limit specified)
 result.offset;     // number - offset used
-result.hasMore;    // boolean - more pages available
+result.hasMore;    // boolean - more pages available (false when no limit)
 
-// Note: Maximum limit is 1000 records per request
+// Note: Omitting `limit` returns all matching records. Max limit is controlled by `maxLimit` config (default: 1000).
 
-// Calculate pagination info
-const totalPages = Math.ceil(result.total / result.limit);
-const currentPage = Math.floor(result.offset / result.limit) + 1;
+// Calculate pagination info (when using explicit limit)
+const totalPages = result.limit ? Math.ceil(result.total / result.limit) : 1;
+const currentPage = result.limit ? Math.floor(result.offset / result.limit) + 1 : 1;
 
 // Multi-column sorting
 const sorted = await sdk.users.list({
@@ -1062,12 +1063,13 @@ Commands:
   init                 Create a postgresdk.config.ts file
   generate             Generate SDK from database
   pull                 Pull SDK from API endpoint
+  install-skill        Install Claude Code skill for PostgreSDK
   version              Show version
   help                 Show help
 
 Options:
   -c, --config <path>  Path to config file (default: postgresdk.config.ts)
-  --force, -y          Delete stale files without prompting (generate & pull)
+  --force, -y          Delete stale files without prompting (generate & pull); overwrite existing skill (install-skill)
 
 Init subcommands/flags:
   init pull            Generate pull-only config (alias for --sdk)
@@ -1083,6 +1085,7 @@ Examples:
   npx postgresdk@latest generate --force                  # Skip stale file prompts
   npx postgresdk@latest pull --from=https://api.com --output=./src/sdk
   npx postgresdk@latest pull --from=https://api.com --output=./src/sdk --force
+  npx postgresdk@latest install-skill                      # Install Claude Code skill
 ```
 
 ### Generated Tests

package/dist/cli-install-skill.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Install the PostgreSDK Claude Code skill into the current project.
+ * Copies skills/postgresdk/SKILL.md → .claude/skills/postgresdk/SKILL.md
+ */
+export declare function installSkillCommand(args: string[]): Promise<void>;

package/dist/cli.js

@@ -1221,7 +1221,7 @@ function generateExampleValue(column) {
 }
 function generateQueryParams(table, enums) {
   const params = {
-    limit: "number - Max records to return (default: 50)",
+    limit: "number - Max records to return (omit for all)",
     offset: "number - Records to skip",
     orderBy: "string | string[] - Field(s) to sort by",
     order: "'asc' | 'desc' | ('asc' | 'desc')[] - Sort direction(s)"
@@ -2483,6 +2483,44 @@ var init_cli_pull = __esm(() => {
   init_cli_utils();
 });
 
+// src/cli-install-skill.ts
+var exports_cli_install_skill = {};
+__export(exports_cli_install_skill, {
+  installSkillCommand: () => installSkillCommand
+});
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, mkdirSync, existsSync as existsSync5 } from "node:fs";
+import { join as join4, dirname as dirname4 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+async function installSkillCommand(args) {
+  const force = parseForceFlag(args);
+  const destDir = join4(process.cwd(), ".claude", "skills", "postgresdk");
+  const destPath = join4(destDir, "SKILL.md");
+  if (existsSync5(destPath) && !force) {
+    console.log("⚠️  Skill already exists at .claude/skills/postgresdk/SKILL.md");
+    console.log("   Use --force to overwrite.");
+    return;
+  }
+  const srcPath = join4(__dirname3, "..", "skills", "postgresdk", "SKILL.md");
+  if (!existsSync5(srcPath)) {
+    console.error("❌ Could not find bundled skill file. This is a bug — please report it.");
+    process.exit(1);
+  }
+  const content = readFileSync3(srcPath, "utf-8");
+  mkdirSync(destDir, { recursive: true });
+  writeFileSync2(destPath, content, "utf-8");
+  console.log("✅ Installed PostgreSDK skill to .claude/skills/postgresdk/SKILL.md");
+  console.log("");
+  console.log("   Claude Code will now use this skill when you ask about your");
+  console.log("   generated API or SDK. Try asking it to help with queries,");
+  console.log("   filtering, includes, auth setup, or transactions.");
+}
+var __filename3, __dirname3;
+var init_cli_install_skill = __esm(() => {
+  init_cli_utils();
+  __filename3 = fileURLToPath2(import.meta.url);
+  __dirname3 = dirname4(__filename3);
+});
+
 // src/index.ts
 var import_config = __toESM(require_config(), 1);
 import { join as join2, relative, dirname as dirname2 } from "node:path";
@@ -2920,7 +2958,7 @@ export const Upsert${Type}Schema = z.object({
 
 // src/emit-params-zod.ts
 init_utils();
-function emitParamsZod(table, graph) {
+function emitParamsZod(table, graph, opts) {
   const Type = pascal(table.name);
   const columnNames = table.columns.map((c) => `"${c.name}"`).join(", ");
   const pkCols = Array.isArray(table.pk) ? table.pk : table.pk ? [table.pk] : [];
@@ -2937,7 +2975,7 @@ export const ${Type}PkSchema = ${pkSchema};
 // Schema for list query parameters
 export const ${Type}ListParamsSchema = z.object({
   include: ${includeSpecSchema}.optional(),
-  limit: z.number().int().positive().max(1000).optional(),
+  limit: z.number().int().positive()${opts.maxLimit > 0 ? `.max(${opts.maxLimit})` : ""}.optional(),
   offset: z.number().int().nonnegative().optional(),
   where: z.any().optional(),
   vector: VectorSearchParamsSchema.optional(),
@@ -2959,12 +2997,12 @@ export type ${Type}OrderParams = z.infer<typeof ${Type}OrderParamsSchema>;
 }
 
 // src/emit-shared-params-zod.ts
-function emitSharedParamsZod() {
+function emitSharedParamsZod(opts) {
   return `import { z } from "zod";
 
 // Shared pagination schema (used across all tables)
 export const PaginationParamsSchema = z.object({
-  limit: z.number().int().positive().max(1000).optional(),
+  limit: z.number().int().positive()${opts.maxLimit > 0 ? `.max(${opts.maxLimit})` : ""}.optional(),
   offset: z.number().int().nonnegative().optional()
 }).strict();
 
@@ -2996,8 +3034,8 @@ export interface PaginatedResponse<T> {
   data: T[];
   /** Total number of records matching the query (across all pages) */
   total: number;
-  /** Maximum number of records per page */
-  limit: number;
+  /** Maximum number of records per page (absent when no limit was specified) */
+  limit?: number;
   /** Number of records skipped (for pagination) */
   offset: number;
   /** Whether there are more records available after this page */
@@ -3072,7 +3110,7 @@ const listSchema = z.object({
   include: z.any().optional(),
   select: z.array(z.string()).min(1).optional(),
   exclude: z.array(z.string()).min(1).optional(),
-  limit: z.number().int().positive().max(1000).optional(),
+  limit: z.number().int().positive()${opts.maxLimit > 0 ? `.max(${opts.maxLimit})` : ""}.optional(),
   offset: z.number().int().min(0).optional(),
   orderBy: z.union([columnEnum, z.array(columnEnum)]).optional(),
   order: z.union([z.enum(["asc", "desc"]), z.array(z.enum(["asc", "desc"]))]).optional(),
@@ -3985,7 +4023,7 @@ ${hasJsonbColumns ? `  /**
    * @param params.where - Filter conditions using operators like $eq, $gt, $in, $like, etc.
    * @param params.orderBy - Column(s) to sort by
    * @param params.order - Sort direction(s): "asc" or "desc"
-   * @param params.limit - Maximum number of records to return (default: 50, max: 1000)
+   * @param params.limit - Maximum number of records to return${opts.maxLimit > 0 ? ` (max: ${opts.maxLimit})` : ""}. Omit to return all matching records.
    * @param params.offset - Number of records to skip for pagination
    * @param params.include - Related records to include (return type automatically infers included relations)
    * @returns Paginated results with all fields (and included relations if specified)
@@ -4085,7 +4123,7 @@ ${hasJsonbColumns ? `  /**
    * @param params.where - Filter conditions using operators like $eq, $gt, $in, $like, etc.
    * @param params.orderBy - Column(s) to sort by
    * @param params.order - Sort direction(s): "asc" or "desc"
-   * @param params.limit - Maximum number of records to return (default: 50, max: 1000)
+   * @param params.limit - Maximum number of records to return${opts.maxLimit > 0 ? ` (max: ${opts.maxLimit})` : ""}. Omit to return all matching records.
    * @param params.offset - Number of records to skip for pagination
    * @param params.include - Related records to include (return type automatically infers included relations)
    * @returns Paginated results with all fields (and included relations if specified)
@@ -6579,7 +6617,7 @@ export async function listRecords(
   }
 ): 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, trigram, distinctOn, includeSoftDeleted } = params;
+    const { where: whereClause, limit, offset = 0, include, orderBy, order, vector, trigram, distinctOn, includeSoftDeleted } = params;
 
     // DISTINCT ON support
     const distinctCols: string[] | null = distinctOn ? (Array.isArray(distinctOn) ? distinctOn : [distinctOn]) : null;
@@ -6715,10 +6753,22 @@ export async function listRecords(
       orderBySQL = buildOrderBySQL(userOrderCols, userDirs);
     }
 
-    // Add limit and offset params
-    const limitParam = \`$\${paramIndex}\`;
-    const offsetParam = \`$\${paramIndex + 1}\`;
-    const allParams = [...queryParams, ...whereParams, limit, offset];
+    // Add limit and offset params (conditional — omit LIMIT clause when limit is undefined)
+    let limitOffsetSQL: string;
+    let allParams: any[];
+    if (limit !== undefined) {
+      const limitParam = \`$\${paramIndex}\`;
+      const offsetParam = \`$\${paramIndex + 1}\`;
+      limitOffsetSQL = \`LIMIT \${limitParam} OFFSET \${offsetParam}\`;
+      allParams = [...queryParams, ...whereParams, limit, offset];
+    } else if (offset > 0) {
+      const offsetParam = \`$\${paramIndex}\`;
+      limitOffsetSQL = \`OFFSET \${offsetParam}\`;
+      allParams = [...queryParams, ...whereParams, offset];
+    } else {
+      limitOffsetSQL = '';
+      allParams = [...queryParams, ...whereParams];
+    }
 
     // Get total count for pagination
     const countText = distinctCols
@@ -6734,9 +6784,9 @@ export async function listRecords(
       // 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}\`;
+      text = \`SELECT * FROM (\${innerQuery}) __distinct \${orderBySQL} \${limitOffsetSQL}\`.trim();
     } else {
-      text = \`SELECT \${selectClause} FROM "\${ctx.table}" \${whereSQL} \${orderBySQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
+      text = \`SELECT \${selectClause} FROM "\${ctx.table}" \${whereSQL} \${orderBySQL} \${limitOffsetSQL}\`.trim();
     }
     log.debug(\`LIST \${ctx.table} SQL:\`, text, "params:", allParams);
 
@@ -6744,7 +6794,7 @@ export async function listRecords(
     const parsedRows = parseVectorColumns(rows, ctx.vectorColumns);
 
     // Calculate hasMore
-    const hasMore = offset + limit < total;
+    const hasMore = limit !== undefined ? offset + limit < total : false;
 
     const metadata = {
       data: parsedRows,
@@ -7784,6 +7834,7 @@ async function generate(configPath, options) {
     clientDir = join2(originalClientDir, "sdk");
   }
   const serverFramework = cfg.serverFramework || "hono";
+  const maxLimit = cfg.maxLimit ?? 1000;
   const generateTests = cfg.tests?.generate ?? false;
   const originalTestDir = cfg.tests?.output || "./api/tests";
   let testDir = originalTestDir;
@@ -7812,7 +7863,7 @@ async function generate(configPath, options) {
   files.push({ path: join2(clientDir, "include-spec.ts"), content: includeSpec });
   const includeResolver = emitIncludeResolver(graph, cfg.useJsExtensions);
   files.push({ path: join2(clientDir, "include-resolver.ts"), content: includeResolver });
-  files.push({ path: join2(clientDir, "params", "shared.ts"), content: emitSharedParamsZod() });
+  files.push({ path: join2(clientDir, "params", "shared.ts"), content: emitSharedParamsZod({ maxLimit }) });
   files.push({ path: join2(clientDir, "types", "shared.ts"), content: emitSharedTypes() });
   files.push({ path: join2(clientDir, "base-client.ts"), content: emitBaseClient() });
   files.push({ path: join2(clientDir, "where-types.ts"), content: emitWhereTypes() });
@@ -7849,7 +7900,7 @@ async function generate(configPath, options) {
     const zodSrc = emitZod(table, { numericMode }, model.enums);
     files.push({ path: join2(serverDir, "zod", `${table.name}.ts`), content: zodSrc });
     files.push({ path: join2(clientDir, "zod", `${table.name}.ts`), content: zodSrc });
-    const paramsZodSrc = emitParamsZod(table, graph);
+    const paramsZodSrc = emitParamsZod(table, graph, { maxLimit });
     files.push({ path: join2(clientDir, "params", `${table.name}.ts`), content: paramsZodSrc });
     let routeContent;
     if (serverFramework === "hono") {
@@ -7859,7 +7910,8 @@ async function generate(configPath, options) {
         includeMethodsDepth: cfg.includeMethodsDepth || 2,
         authStrategy: getAuthStrategy(normalizedAuth),
         useJsExtensions: cfg.useJsExtensions,
-        apiPathPrefix: cfg.apiPathPrefix || "/v1"
+        apiPathPrefix: cfg.apiPathPrefix || "/v1",
+        maxLimit
       });
     } else {
       throw new Error(`Framework "${serverFramework}" is not yet supported. Currently only "hono" is available.`);
@@ -7875,7 +7927,8 @@ async function generate(configPath, options) {
         exposeHardDelete,
         useJsExtensions: cfg.useJsExtensionsClient,
         includeMethodsDepth: cfg.includeMethodsDepth ?? 2,
-        skipJunctionTables: cfg.skipJunctionTables ?? true
+        skipJunctionTables: cfg.skipJunctionTables ?? true,
+        maxLimit
       }, model)
     });
   }
@@ -8020,13 +8073,13 @@ async function generate(configPath, options) {
 // src/cli.ts
 var import_config2 = __toESM(require_config(), 1);
 import { resolve as resolve3 } from "node:path";
-import { readFileSync as readFileSync3 } from "node:fs";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { dirname as dirname4, join as join4 } from "node:path";
+import { readFileSync as readFileSync4 } from "node:fs";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { dirname as dirname5, join as join5 } from "node:path";
 init_cli_utils();
-var __filename3 = fileURLToPath2(import.meta.url);
-var __dirname3 = dirname4(__filename3);
-var packageJson = JSON.parse(readFileSync3(join4(__dirname3, "../package.json"), "utf-8"));
+var __filename4 = fileURLToPath3(import.meta.url);
+var __dirname4 = dirname5(__filename4);
+var packageJson = JSON.parse(readFileSync4(join5(__dirname4, "../package.json"), "utf-8"));
 var VERSION = packageJson.version;
 var args = process.argv.slice(2);
 var command = args[0];
@@ -8045,6 +8098,7 @@ Commands:
   init                 Create a postgresdk.config.ts file
   generate, gen        Generate SDK from database
   pull                 Pull SDK from API endpoint
+  install-skill        Install Claude Code skill for PostgreSDK
   version              Show version
   help                 Show help
 
@@ -8062,6 +8116,9 @@ Pull Options:
   --force, -y          Delete stale files without prompting
   -c, --config <path>  Path to config file with pull settings
 
+Install-skill Options:
+  --force, -y          Overwrite existing skill
+
 Examples:
   postgresdk init                        # Create config file
   postgresdk generate                    # Generate using postgresdk.config.ts
@@ -8069,6 +8126,7 @@ Examples:
   postgresdk generate -c custom.config.ts
   postgresdk pull --from=https://api.com --output=./src/sdk
   postgresdk pull                        # Pull using config file
+  postgresdk install-skill               # Install Claude Code skill
 `);
   process.exit(0);
 }
@@ -8091,6 +8149,9 @@ if (command === "init") {
 } else if (command === "pull") {
   const { pullCommand: pullCommand2 } = await Promise.resolve().then(() => (init_cli_pull(), exports_cli_pull));
   await pullCommand2(args.slice(1));
+} else if (command === "install-skill") {
+  const { installSkillCommand: installSkillCommand2 } = await Promise.resolve().then(() => (init_cli_install_skill(), exports_cli_install_skill));
+  await installSkillCommand2(args.slice(1));
 } else {
   console.error(`❌ Unknown command: ${command}`);
   console.error(`Run 'postgresdk help' for usage information`);

package/dist/emit-client.d.ts

@@ -6,6 +6,7 @@ export declare function emitClient(table: Table, graph: Graph, opts: {
     useJsExtensions?: boolean;
     includeMethodsDepth?: number;
     skipJunctionTables?: boolean;
+    maxLimit: number;
 }, model?: Model): string;
 export declare function emitClientIndex(tables: Table[], useJsExtensions?: boolean, graph?: Graph, includeOpts?: {
     maxDepth: number;

package/dist/emit-params-zod.d.ts

@@ -1,3 +1,5 @@
 import type { Table } from "./introspect";
 import type { Graph } from "./rel-classify";
-export declare function emitParamsZod(table: Table, graph: Graph): string;
+export declare function emitParamsZod(table: Table, graph: Graph, opts: {
+    maxLimit: number;
+}): string;

package/dist/emit-routes-hono.d.ts

@@ -10,4 +10,5 @@ export declare function emitHonoRoutes(table: Table, _graph: Graph, opts: {
     authStrategy?: string;
     useJsExtensions?: boolean;
     apiPathPrefix: string;
+    maxLimit: number;
 }): string;

package/dist/emit-routes.d.ts

@@ -18,4 +18,5 @@ export declare function emitRoutes(table: Table, _graph: Graph, opts: {
     softDeleteColumn: string | null;
     includeMethodsDepth: number;
     authStrategy?: string;
+    maxLimit: number;
 }): string;

package/dist/emit-shared-params-zod.d.ts

@@ -1 +1,3 @@
-export declare function emitSharedParamsZod(): string;
+export declare function emitSharedParamsZod(opts: {
+    maxLimit: number;
+}): string;

package/dist/index.js

@@ -1220,7 +1220,7 @@ function generateExampleValue(column) {
 }
 function generateQueryParams(table, enums) {
   const params = {
-    limit: "number - Max records to return (default: 50)",
+    limit: "number - Max records to return (omit for all)",
     offset: "number - Records to skip",
     orderBy: "string | string[] - Field(s) to sort by",
     order: "'asc' | 'desc' | ('asc' | 'desc')[] - Sort direction(s)"
@@ -1960,7 +1960,7 @@ export const Upsert${Type}Schema = z.object({
 
 // src/emit-params-zod.ts
 init_utils();
-function emitParamsZod(table, graph) {
+function emitParamsZod(table, graph, opts) {
   const Type = pascal(table.name);
   const columnNames = table.columns.map((c) => `"${c.name}"`).join(", ");
   const pkCols = Array.isArray(table.pk) ? table.pk : table.pk ? [table.pk] : [];
@@ -1977,7 +1977,7 @@ export const ${Type}PkSchema = ${pkSchema};
 // Schema for list query parameters
 export const ${Type}ListParamsSchema = z.object({
   include: ${includeSpecSchema}.optional(),
-  limit: z.number().int().positive().max(1000).optional(),
+  limit: z.number().int().positive()${opts.maxLimit > 0 ? `.max(${opts.maxLimit})` : ""}.optional(),
   offset: z.number().int().nonnegative().optional(),
   where: z.any().optional(),
   vector: VectorSearchParamsSchema.optional(),
@@ -1999,12 +1999,12 @@ export type ${Type}OrderParams = z.infer<typeof ${Type}OrderParamsSchema>;
 }
 
 // src/emit-shared-params-zod.ts
-function emitSharedParamsZod() {
+function emitSharedParamsZod(opts) {
   return `import { z } from "zod";
 
 // Shared pagination schema (used across all tables)
 export const PaginationParamsSchema = z.object({
-  limit: z.number().int().positive().max(1000).optional(),
+  limit: z.number().int().positive()${opts.maxLimit > 0 ? `.max(${opts.maxLimit})` : ""}.optional(),
   offset: z.number().int().nonnegative().optional()
 }).strict();
 
@@ -2036,8 +2036,8 @@ export interface PaginatedResponse<T> {
   data: T[];
   /** Total number of records matching the query (across all pages) */
   total: number;
-  /** Maximum number of records per page */
-  limit: number;
+  /** Maximum number of records per page (absent when no limit was specified) */
+  limit?: number;
   /** Number of records skipped (for pagination) */
   offset: number;
   /** Whether there are more records available after this page */
@@ -2112,7 +2112,7 @@ const listSchema = z.object({
   include: z.any().optional(),
   select: z.array(z.string()).min(1).optional(),
   exclude: z.array(z.string()).min(1).optional(),
-  limit: z.number().int().positive().max(1000).optional(),
+  limit: z.number().int().positive()${opts.maxLimit > 0 ? `.max(${opts.maxLimit})` : ""}.optional(),
   offset: z.number().int().min(0).optional(),
   orderBy: z.union([columnEnum, z.array(columnEnum)]).optional(),
   order: z.union([z.enum(["asc", "desc"]), z.array(z.enum(["asc", "desc"]))]).optional(),
@@ -3025,7 +3025,7 @@ ${hasJsonbColumns ? `  /**
    * @param params.where - Filter conditions using operators like $eq, $gt, $in, $like, etc.
    * @param params.orderBy - Column(s) to sort by
    * @param params.order - Sort direction(s): "asc" or "desc"
-   * @param params.limit - Maximum number of records to return (default: 50, max: 1000)
+   * @param params.limit - Maximum number of records to return${opts.maxLimit > 0 ? ` (max: ${opts.maxLimit})` : ""}. Omit to return all matching records.
    * @param params.offset - Number of records to skip for pagination
    * @param params.include - Related records to include (return type automatically infers included relations)
    * @returns Paginated results with all fields (and included relations if specified)
@@ -3125,7 +3125,7 @@ ${hasJsonbColumns ? `  /**
    * @param params.where - Filter conditions using operators like $eq, $gt, $in, $like, etc.
    * @param params.orderBy - Column(s) to sort by
    * @param params.order - Sort direction(s): "asc" or "desc"
-   * @param params.limit - Maximum number of records to return (default: 50, max: 1000)
+   * @param params.limit - Maximum number of records to return${opts.maxLimit > 0 ? ` (max: ${opts.maxLimit})` : ""}. Omit to return all matching records.
    * @param params.offset - Number of records to skip for pagination
    * @param params.include - Related records to include (return type automatically infers included relations)
    * @returns Paginated results with all fields (and included relations if specified)
@@ -5619,7 +5619,7 @@ export async function listRecords(
   }
 ): 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, trigram, distinctOn, includeSoftDeleted } = params;
+    const { where: whereClause, limit, offset = 0, include, orderBy, order, vector, trigram, distinctOn, includeSoftDeleted } = params;
 
     // DISTINCT ON support
     const distinctCols: string[] | null = distinctOn ? (Array.isArray(distinctOn) ? distinctOn : [distinctOn]) : null;
@@ -5755,10 +5755,22 @@ export async function listRecords(
       orderBySQL = buildOrderBySQL(userOrderCols, userDirs);
     }
 
-    // Add limit and offset params
-    const limitParam = \`$\${paramIndex}\`;
-    const offsetParam = \`$\${paramIndex + 1}\`;
-    const allParams = [...queryParams, ...whereParams, limit, offset];
+    // Add limit and offset params (conditional — omit LIMIT clause when limit is undefined)
+    let limitOffsetSQL: string;
+    let allParams: any[];
+    if (limit !== undefined) {
+      const limitParam = \`$\${paramIndex}\`;
+      const offsetParam = \`$\${paramIndex + 1}\`;
+      limitOffsetSQL = \`LIMIT \${limitParam} OFFSET \${offsetParam}\`;
+      allParams = [...queryParams, ...whereParams, limit, offset];
+    } else if (offset > 0) {
+      const offsetParam = \`$\${paramIndex}\`;
+      limitOffsetSQL = \`OFFSET \${offsetParam}\`;
+      allParams = [...queryParams, ...whereParams, offset];
+    } else {
+      limitOffsetSQL = '';
+      allParams = [...queryParams, ...whereParams];
+    }
 
     // Get total count for pagination
     const countText = distinctCols
@@ -5774,9 +5786,9 @@ export async function listRecords(
       // 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}\`;
+      text = \`SELECT * FROM (\${innerQuery}) __distinct \${orderBySQL} \${limitOffsetSQL}\`.trim();
     } else {
-      text = \`SELECT \${selectClause} FROM "\${ctx.table}" \${whereSQL} \${orderBySQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
+      text = \`SELECT \${selectClause} FROM "\${ctx.table}" \${whereSQL} \${orderBySQL} \${limitOffsetSQL}\`.trim();
     }
     log.debug(\`LIST \${ctx.table} SQL:\`, text, "params:", allParams);
 
@@ -5784,7 +5796,7 @@ export async function listRecords(
     const parsedRows = parseVectorColumns(rows, ctx.vectorColumns);
 
     // Calculate hasMore
-    const hasMore = offset + limit < total;
+    const hasMore = limit !== undefined ? offset + limit < total : false;
 
     const metadata = {
       data: parsedRows,
@@ -6824,6 +6836,7 @@ async function generate(configPath, options) {
     clientDir = join2(originalClientDir, "sdk");
   }
   const serverFramework = cfg.serverFramework || "hono";
+  const maxLimit = cfg.maxLimit ?? 1000;
   const generateTests = cfg.tests?.generate ?? false;
   const originalTestDir = cfg.tests?.output || "./api/tests";
   let testDir = originalTestDir;
@@ -6852,7 +6865,7 @@ async function generate(configPath, options) {
   files.push({ path: join2(clientDir, "include-spec.ts"), content: includeSpec });
   const includeResolver = emitIncludeResolver(graph, cfg.useJsExtensions);
   files.push({ path: join2(clientDir, "include-resolver.ts"), content: includeResolver });
-  files.push({ path: join2(clientDir, "params", "shared.ts"), content: emitSharedParamsZod() });
+  files.push({ path: join2(clientDir, "params", "shared.ts"), content: emitSharedParamsZod({ maxLimit }) });
   files.push({ path: join2(clientDir, "types", "shared.ts"), content: emitSharedTypes() });
   files.push({ path: join2(clientDir, "base-client.ts"), content: emitBaseClient() });
   files.push({ path: join2(clientDir, "where-types.ts"), content: emitWhereTypes() });
@@ -6889,7 +6902,7 @@ async function generate(configPath, options) {
     const zodSrc = emitZod(table, { numericMode }, model.enums);
     files.push({ path: join2(serverDir, "zod", `${table.name}.ts`), content: zodSrc });
     files.push({ path: join2(clientDir, "zod", `${table.name}.ts`), content: zodSrc });
-    const paramsZodSrc = emitParamsZod(table, graph);
+    const paramsZodSrc = emitParamsZod(table, graph, { maxLimit });
     files.push({ path: join2(clientDir, "params", `${table.name}.ts`), content: paramsZodSrc });
     let routeContent;
     if (serverFramework === "hono") {
@@ -6899,7 +6912,8 @@ async function generate(configPath, options) {
         includeMethodsDepth: cfg.includeMethodsDepth || 2,
         authStrategy: getAuthStrategy(normalizedAuth),
         useJsExtensions: cfg.useJsExtensions,
-        apiPathPrefix: cfg.apiPathPrefix || "/v1"
+        apiPathPrefix: cfg.apiPathPrefix || "/v1",
+        maxLimit
       });
     } else {
       throw new Error(`Framework "${serverFramework}" is not yet supported. Currently only "hono" is available.`);
@@ -6915,7 +6929,8 @@ async function generate(configPath, options) {
         exposeHardDelete,
         useJsExtensions: cfg.useJsExtensionsClient,
         includeMethodsDepth: cfg.includeMethodsDepth ?? 2,
-        skipJunctionTables: cfg.skipJunctionTables ?? true
+        skipJunctionTables: cfg.skipJunctionTables ?? true,
+        maxLimit
       }, model)
     });
   }

package/dist/types.d.ts

@@ -38,6 +38,8 @@ export interface Config {
     skipJunctionTables?: boolean;
     serverFramework?: "hono" | "express" | "fastify";
     apiPathPrefix?: string;
+    /** Maximum allowed value for the `limit` parameter in list operations (default: 1000). Set to 0 to disable. */
+    maxLimit?: number;
     auth?: AuthConfigInput;
     pullToken?: string;
     pull?: PullConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.19.3",
+  "version": "0.19.5",
   "description": "Generate a typed server/client SDK from a Postgres schema (includes, Zod, Hono).",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -22,7 +23,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 && bun test test/test-trigram-search.test.ts && bun test test/test-soft-delete-config.test.ts && bun test test/test-soft-delete-include-loader.test.ts && bun test test/test-soft-delete-nested-include.test.ts && bun test test/test-transaction.test.ts && bun test test/test-nullable-belongs-to.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 && bun test test/test-soft-delete-config.test.ts && bun test test/test-soft-delete-include-loader.test.ts && bun test test/test-soft-delete-nested-include.test.ts && bun test test/test-transaction.test.ts && bun test test/test-nullable-belongs-to.test.ts && bun test test/test-no-default-limit.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",

package/skills/postgresdk/SKILL.md

@@ -0,0 +1,394 @@
+---
+name: postgresdk
+description: "How to use a PostgreSDK-generated API and client SDK. Use this skill whenever the user is working with code generated by PostgreSDK — including the typed client SDK (e.g., `sdk.users.list()`, `sdk.books.create()`), the generated Hono API server (router, routes, auth middleware), or the CONTRACT.md/contract.ts reference files. Trigger on: SDK method calls like `.list()`, `.getByPk()`, `.create()`, `.update()`, `.upsert()`, `.$transaction()`, `.listWith*()`, WHERE clause operators like `$ilike`, `$in`, `$gte`, `$jsonbContains`, mentions of `postgresdk`, `CONTRACT.md`, `createRouter`, `BaseClient`, `PaginatedResponse`, `InsertX`/`SelectX`/`UpdateX` types, `postgresdk.config.ts`, or any questions about filtering, includes, pagination, vector search, or trigram search in the context of a generated API."
+---
+
+# PostgreSDK Assistant
+
+You are helping a developer who is using code generated by [PostgreSDK](https://github.com/nickreese/postgresdk) — a tool that generates a fully typed Hono API server and TypeScript client SDK from a PostgreSQL database schema.
+
+## First: Discover the Generated Code
+
+The output directory is fully configurable via `postgresdk.config.ts` — don't assume paths like `./api/server` or `./api/client`. Discover where the generated code actually lives:
+
+1. **Search for `postgresdk.config.ts`** — if present, read the `outDir` value. It can be a string (e.g. `"./generated"`) or an object (`{ client: "./sdk", server: "./backend" }`). This tells you where the generated directories are.
+2. **Search for generated marker files** — if no config, glob for `**/router.ts`, `**/base-client.ts`, or `**/CONTRACT.md` and look for the `AUTO-GENERATED FILE` header to find the generated output directories.
+
+Once you've found the generated directories, identify which side the user is working on:
+
+**API-side** (runs the server):
+- Has a directory containing `router.ts`, `routes/*.ts`, `contract.ts`, `sdk-bundle.ts`
+- Has `postgresdk.config.ts` with `connectionString`
+- Asks about `createRouter`, `onRequest`, auth config, deployment, database drivers
+
+**SDK-side** (consumes the API):
+- Has a directory containing `base-client.ts`, table client files (e.g. `users.ts`), `CONTRACT.md`
+- May have `postgresdk.config.ts` with a `pull` section instead of `connectionString`
+- Asks about `sdk.tableName.method()`, filtering, includes, transactions
+
+**Both** — common when a single `outDir` generates server and client subdirectories.
+
+## Second: Read the Contract
+
+The generated `CONTRACT.md` is the single source of truth for the user's specific schema. It contains every table, field, type, method, endpoint, and relationship. Read it before answering schema-specific questions.
+
+Search with `**/CONTRACT.md` and look for the one with the `AUTO-GENERATED` header. It exists in both the server and client output directories — either copy works, they're identical.
+
+If you can't find it, ask the user where their generated code lives.
+
+## SDK Reference
+
+### Initialization
+
+```typescript
+// Import path depends on outDir config — find the generated client directory
+import { SDK } from '<client-dir>';
+
+const sdk = new SDK({
+  baseUrl: 'http://localhost:3000',
+  auth: {
+    apiKey: 'your-key',           // API key auth
+    // OR
+    jwt: 'your-token',           // Static JWT
+    // OR
+    jwt: async () => getToken(), // Async JWT provider
+  }
+});
+```
+
+### CRUD Operations
+
+Every table gets these methods (assuming single primary key):
+
+```typescript
+// Create
+const item = await sdk.users.create({ name: 'Alice', email: 'alice@example.com' });
+
+// Read
+const user = await sdk.users.getByPk('id-123');           // single record or null
+const result = await sdk.users.list({ limit: 20 });       // paginated
+
+// Update
+const updated = await sdk.users.update('id-123', { name: 'Bob' });
+
+// Upsert (insert or update on conflict)
+const upserted = await sdk.users.upsert({
+  where:  { email: 'alice@example.com' },       // unique constraint columns
+  create: { email: 'alice@example.com', name: 'Alice' },
+  update: { name: 'Alice Updated' },
+});
+
+// Delete
+await sdk.users.hardDelete('id-123');   // permanent
+await sdk.users.softDelete('id-123');   // sets soft-delete column (if configured)
+```
+
+### Paginated Response Shape
+
+All `list()` calls return:
+```typescript
+{
+  data: T[];          // array of records
+  total: number;      // total matching records (respects WHERE)
+  limit?: number;     // page size (absent when no limit)
+  offset: number;     // current offset
+  hasMore: boolean;   // more pages available
+}
+```
+
+### WHERE Filtering
+
+Root-level keys are AND'd. Use `$or`/`$and` for logic (2 nesting levels max).
+
+```typescript
+await sdk.users.list({
+  where: {
+    age: { $gte: 18, $lt: 65 },
+    email: { $ilike: '%@company.com' },
+    status: { $in: ['active', 'pending'] },
+    deleted_at: { $is: null },
+    $or: [{ role: 'admin' }, { role: 'mod' }]
+  }
+});
+```
+
+**Available operators:**
+
+| Operator | SQL | Applies to |
+|----------|-----|------------|
+| `$eq`, `$ne` | `=`, `!=` | All types |
+| `$gt`, `$gte`, `$lt`, `$lte` | `>`, `>=`, `<`, `<=` | Number, Date |
+| `$in`, `$nin` | `IN`, `NOT IN` | All types |
+| `$like`, `$ilike` | `LIKE`, `ILIKE` | Strings |
+| `$is`, `$isNot` | `IS NULL`, `IS NOT NULL` | Nullable fields |
+| `$similarity`, `$wordSimilarity`, `$strictWordSimilarity` | pg_trgm operators | Strings (requires pg_trgm) |
+| `$jsonbContains` | `@>` | JSONB |
+| `$jsonbContainedBy` | `<@` | JSONB |
+| `$jsonbHasKey` | `?` | JSONB |
+| `$jsonbHasAnyKeys` | `?\|` | JSONB |
+| `$jsonbHasAllKeys` | `?&` | JSONB |
+| `$jsonbPath` | Path-based query | JSONB |
+| `$or`, `$and` | `OR`, `AND` | Logical combinators |
+
+### Sorting
+
+```typescript
+// Single column
+await sdk.users.list({ orderBy: 'created_at', order: 'desc' });
+
+// Multi-column with per-column direction
+await sdk.users.list({
+  orderBy: ['status', 'created_at'],
+  order: ['asc', 'desc']
+});
+```
+
+### DISTINCT ON
+
+```typescript
+const latestPerUser = await sdk.events.list({
+  distinctOn: 'user_id',
+  orderBy: 'created_at',
+  order: 'desc'
+});
+```
+
+### Field Selection
+
+```typescript
+// Only return specific fields
+await sdk.users.list({ select: ['id', 'email', 'name'] });
+
+// Return all fields except these
+await sdk.users.list({ exclude: ['password_hash', 'secret_token'] });
+
+// Works on single-record operations too
+await sdk.users.create(data, { select: ['id', 'email'] });
+await sdk.users.update(id, patch, { exclude: ['updated_at'] });
+await sdk.users.getByPk(id, { select: ['id', 'name'] });
+```
+
+### Relationships & Includes
+
+**Generic include:**
+```typescript
+const result = await sdk.authors.list({
+  include: { books: true }
+});
+// result.data[0].books is SelectBooks[]
+```
+
+**Typed convenience methods** (generated per-table based on relationships):
+```typescript
+// listWith* and getByPkWith* — check CONTRACT.md for what's available
+const result = await sdk.authors.listWithBooks({ limit: 10 });
+const author = await sdk.authors.getByPkWithBooksAndTags('id');
+
+// Control included relations
+await sdk.authors.listWithBooks({
+  booksInclude: { orderBy: 'published_at', order: 'desc', limit: 5 }
+});
+```
+
+**Nested includes:**
+```typescript
+const result = await sdk.authors.list({
+  include: { books: { tags: true } }
+});
+// result.data[0].books[0].tags is SelectTags[]
+```
+
+**Select/exclude on includes:**
+```typescript
+await sdk.authors.list({
+  select: ['id', 'name'],
+  include: {
+    books: { select: ['id', 'title'], orderBy: 'published_at', limit: 5 }
+  }
+});
+```
+
+### Atomic Transactions
+
+Use `$`-prefixed lazy builders inside `$transaction`:
+
+```typescript
+const [order, updatedUser] = await sdk.$transaction([
+  sdk.orders.$create({ user_id: user.id, total: 99 }),
+  sdk.users.$update(user.id, { last_order_at: new Date().toISOString() }),
+]);
+// TypeScript infers: [SelectOrders, SelectUsers | null]
+```
+
+Available builders: `$create`, `$update`, `$softDelete`, `$hardDelete`, `$upsert`.
+
+All operations are Zod-validated before `BEGIN`. On failure, the entire transaction rolls back and throws with a `.failedAt` index.
+
+### Soft Deletes
+
+When `softDeleteColumn` is configured in `postgresdk.config.ts`:
+- `softDelete(id)` — sets the column (e.g. `deleted_at = NOW()`)
+- `hardDelete(id)` — permanent `DELETE` (unless `exposeHardDelete: false`)
+- Soft-deleted rows are hidden from `list`/`getByPk` by default
+- Pass `includeSoftDeleted: true` to see them
+
+### Vector Search (pgvector)
+
+For tables with `vector` columns. Results auto-include `_distance`.
+
+```typescript
+const results = await sdk.video_sections.list({
+  vector: {
+    field: 'vision_embedding',
+    query: embeddingArray,         // number[]
+    metric: 'cosine',             // 'cosine' | 'l2' | 'inner'
+    maxDistance: 0.5               // optional threshold
+  },
+  where: { status: 'published' }, // combine with regular filters
+  limit: 10
+});
+// results.data[0]._distance
+```
+
+### Trigram Search (pg_trgm)
+
+Fuzzy text search. Results auto-include `_similarity`.
+
+```typescript
+const results = await sdk.books.list({
+  trigram: {
+    field: 'title',
+    query: 'postgrs',            // typo-tolerant
+    metric: 'similarity',        // 'similarity' | 'wordSimilarity' | 'strictWordSimilarity'
+    threshold: 0.3               // min score 0–1
+  },
+  limit: 10
+});
+```
+
+**Multi-field:** `fields: ['name', 'url']` with `strategy: 'greatest' | 'concat'`, or weighted: `fields: [{ field: 'name', weight: 2 }, { field: 'url', weight: 1 }]`.
+
+Note: `trigram` and `vector` are mutually exclusive on a single `list()` call.
+
+### Type Imports
+
+Import paths below use `<client>` as a placeholder — substitute the actual path to the generated client directory (determined by the `outDir` config).
+
+```typescript
+import { SDK } from '<client>';
+import type { SelectUsers, InsertUsers, UpdateUsers } from '<client>/types/users';
+import type { PaginatedResponse } from '<client>/types/shared';
+
+// Zod schemas (for form validation, etc.)
+import { InsertUsersSchema, UpdateUsersSchema } from '<client>/zod/users';
+
+// Params schemas
+import { UsersListParamsSchema, UsersPkSchema } from '<client>/params/users';
+```
+
+## API Server Reference
+
+### Basic Setup
+
+```typescript
+import { Hono } from 'hono';
+import { serve } from '@hono/node-server';
+import { Client } from 'pg';
+import { createRouter } from '<server>/router'; // path depends on outDir config
+
+const app = new Hono();
+const pg = new Client({ connectionString: process.env.DATABASE_URL });
+await pg.connect();
+
+const apiRouter = createRouter({ pg });
+app.route('/', apiRouter);
+
+serve({ fetch: app.fetch, port: 3000 });
+```
+
+### Auth Configuration (in postgresdk.config.ts)
+
+```typescript
+export default {
+  connectionString: process.env.DATABASE_URL,
+  auth: {
+    // Option A: API key
+    apiKey: process.env.API_KEY,
+
+    // Option B: JWT (supports multiple services)
+    jwt: {
+      services: [
+        { issuer: 'web-app', secret: 'env:WEB_SECRET' },
+        { issuer: 'mobile', secret: 'env:MOBILE_SECRET' },
+      ],
+      audience: 'my-api'   // optional
+    }
+  }
+};
+```
+
+### onRequest Hook
+
+Runs before every endpoint. Use for RLS, audit logging, authorization:
+
+```typescript
+const apiRouter = createRouter({
+  pg,
+  onRequest: async (c, pg) => {
+    const auth = c.get('auth');
+
+    // Set PostgreSQL session variable for RLS
+    if (auth?.kind === 'jwt' && auth.claims?.sub) {
+      await pg.query(`SET LOCAL app.user_id = '${auth.claims.sub}'`);
+    }
+
+    // Scope-based authorization
+    const scopes = auth?.claims?.scopes || [];
+    const table = c.req.path.split('/')[2];
+    if (!hasPermission(scopes, table, c.req.method)) {
+      throw new Error('Forbidden');
+    }
+  }
+});
+```
+
+### Deployment Patterns
+
+- **Serverless** (Vercel, Cloudflare): Use `Pool` with `max: 1` — each instance is ephemeral
+- **Traditional** (Railway, VPS): Use `Pool` with `max: 10` — reuse connections across requests
+- **Edge**: Use `@neondatabase/serverless` Pool, set `useJsExtensions: true` in config
+
+### SDK Distribution
+
+The generated server auto-serves the client SDK:
+- `GET /_psdk/sdk/manifest` — file listing
+- `GET /_psdk/sdk/download` — complete bundle
+- `GET /_psdk/contract.md` — markdown contract
+- `GET /_psdk/contract.json` — JSON contract
+
+Clients pull with: `npx postgresdk@latest pull --from=https://api.example.com --output=./src/sdk`
+
+Protect with `pullToken` in config if needed.
+
+## Key Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `schema` | `"public"` | Database schema to introspect |
+| `outDir` | `"./api"` | Output dir (or `{ client, server }`) |
+| `numericMode` | `"auto"` | `"auto"` / `"number"` / `"string"` |
+| `maxLimit` | `1000` | Max allowed `limit` (0 = no cap) |
+| `includeMethodsDepth` | `2` | Max depth for `listWith*` methods |
+| `dateType` | `"date"` | `"date"` / `"string"` |
+| `useJsExtensions` | `false` | Add `.js` to imports (Edge/Deno) |
+| `delete.softDeleteColumn` | — | Column name for soft deletes |
+| `delete.exposeHardDelete` | `true` | Also expose `hardDelete()` |
+
+## Common Gotchas
+
+- **list() uses POST** — the `list` method sends a POST to `/v1/{table}/list` (not GET) because complex WHERE/include payloads don't fit in query strings. The simple GET endpoint exists too but only supports basic query params.
+- **Composite PKs** — tables with composite primary keys don't get `getByPk`, `update`, `delete`, or `upsert` methods. Use `list` with WHERE filters instead.
+- **Junction tables** — M:N junction tables (like `book_tags`) are detected automatically. The SDK generates include methods that skip the junction table: `sdk.books.listWithTags()` gives you tags directly, not book_tags.
+- **Import paths** — depend entirely on the `outDir` config in `postgresdk.config.ts`. Always discover the actual generated directory before suggesting imports.
+- **Types naming** — `Select{PascalTable}`, `Insert{PascalTable}`, `Update{PascalTable}` (e.g., `SelectUsers`, `InsertUsers`).
+- **Regeneration** — all generated files have `AUTO-GENERATED FILE - DO NOT EDIT` headers. Changes are overwritten on `generate` or `pull`. Extend behavior via `onRequest` hooks, not by editing generated code.