⚠️ Active Development: This project is under active development and is not yet stable for production use. APIs and features may change without notice.
Generate a typed server/client SDK from your PostgreSQL database schema.
postgresdk introspects your Postgres schema and generates two things:
- A Hono API server — typed routes, Zod validation, auth middleware, soft/hard delete, vector & trigram search.
- A TypeScript client SDK — typed CRUD, eager-loading
includes, atomic transactions, type-safewherefiltering, and pagination.
Regenerate any time your schema changes. No hand-written glue, no drift.
Full documentation lives at https://docs.postgresdk.com.
The docs are also published for LLMs / agents (read verbatim):
/llms.txt— index + summary/llms-full.txt— the entire docs as one file/llms-small.txt— trimmed bundle for smaller contexts
Highlights:
- Quick start
- CLI reference (generated from the CLI)
- Configuration reference (generated from the
Configtype) - Filtering & WHERE operators (generated from the source)
- Generated API example (a real
CONTRACT.md)
// ✨ Fully typed client with autocomplete
const user = await sdk.users.create({ name: "Alice", email: "alice@example.com" });
// 🔗 Automatic relationship loading
const { data } = await sdk.users.list({ include: { posts: true } });
// data[0].posts is fully typed Post[]
// 🎯 Advanced filtering with type safety
const filtered = await sdk.users.list({
where: { email: { $ilike: "%@company.com" }, status: "active" },
});- 🚀 Instant SDK generation — point at your database, get a complete SDK
- 🔒 Type safety — full TypeScript types derived from your schema (including enums)
- ✅ Runtime validation — Zod schemas for requests/responses
- 🔗 Smart relationships — 1:N and M:N with eager loading
- 🔍 Vector & trigram search — pgvector and pg_trgm support
- ⚡ Atomic transactions —
sdk.$transaction([...]) - 🔐 Built-in auth — API key and JWT
- 🎯 Sensible defaults — only
connectionStringis required
bunx postgresdk@latest init # create postgresdk.config.ts
bunx postgresdk@latest generate # introspect + generate (alias: gen)// server
import { Hono } from "hono";
import { serve } from "@hono/node-server";
import { Client } from "pg";
import { createRouter } from "./api/server/router";
const app = new Hono();
const pg = new Client({ connectionString: process.env.DATABASE_URL });
await pg.connect();
app.route("/", createRouter({ pg }));
serve({ fetch: app.fetch, port: 3000 });// client
import { SDK } from "./api/client";
const sdk = new SDK({ baseUrl: "http://localhost:3000" });See the quick start for the full walkthrough.
- Node.js 18.17+ (or Bun)
- PostgreSQL 12+
- A TypeScript project to consume the generated code
Currently postgresdk only generates server code for Hono. The config accepts
serverFramework: "hono" | "express" | "fastify", but only Hono is implemented; express/fastify
are reserved and will error. See the docs for the rationale and roadmap.
Docs live in docs/ (Astro Starlight). Reference pages are generated from this
package's own source, so they can't drift.
Not sure which task you need? Run task start for an interactive menu. Otherwise:
task docs:gen # regenerate CLI, config, and operator references
task docs:gen:contract # regenerate the "generated API example" (needs Docker)
task docs:check # typecheck the documented SDK usage vs a generated SDK (needs Docker)
task docs:dev # run the docs site locally
task docs:build # build the static site (emits llms.txt)CI (.github/workflows/docs.yml) enforces all of this: generated pages can't be committed
stale, the site must build, and the documented usage must still typecheck — so docs drift
breaks the build instead of going unnoticed.
MIT