postgresdk 0.3.0 → 0.5.1-alpha.0

package/README.md

@@ -139,7 +139,7 @@ All from your existing database schema. No manual coding required.
 - 🔗 **Smart Relationships** - Automatic handling of 1:N and M:N relationships with eager loading
 - 🔐 **Built-in Auth** - API key and JWT authentication with zero configuration
 - 🎯 **Zero Config** - Works out of the box with sensible defaults
-- 🏗️ **Framework Ready** - Server routes built for Hono, client SDK works anywhere
+- 🏗️ **Framework Ready** - Server routes for Hono (Express & Fastify coming soon), client SDK works anywhere
 - 📦 **Lightweight** - Minimal dependencies, optimized bundle size with shared BaseClient
 - 🔄 **SDK Distribution** - Built-in SDK bundling and pull mechanism for easy client distribution
 
@@ -218,6 +218,8 @@ export default {
   softDeleteColumn: null,              // Column name for soft deletes (e.g., "deleted_at")
   includeDepthLimit: 3,                 // Max depth for nested includes
   dateType: "date",                    // "date" | "string" - How to handle timestamps
+  serverFramework: "hono",             // "hono" | "express" | "fastify" (currently only hono)
+  useJsExtensions: false,              // Add .js to imports (for Vercel Edge, Deno)
   
   // Authentication (optional) - simplified syntax
   auth: {
@@ -493,6 +495,126 @@ const sdk = new SDK({
 });
 ```
 
+## Database Drivers
+
+The generated code works with any PostgreSQL client that implements a simple `query` interface. You can use the standard `pg` driver, Neon's serverless driver, or any other compatible client.
+
+### Node.js `pg` Driver
+
+The standard PostgreSQL driver for Node.js environments. Works everywhere Node.js runs.
+
+Server setup:
+```typescript
+import { Hono } from "hono";
+import { Client } from "pg";
+import { createRouter } from "./generated/server/router";
+
+const app = new Hono();
+
+// Standard pg client
+const pg = new Client({ connectionString: process.env.DATABASE_URL });
+await pg.connect();
+
+// Wire up the generated routes
+const apiRouter = createRouter({ pg });
+app.route("/", apiRouter);
+```
+
+### Neon Serverless Driver (Edge-Compatible)
+
+For edge environments like Vercel Edge Functions or Cloudflare Workers. Uses HTTP/WebSocket instead of TCP connections.
+
+Configuration for Vercel Edge:
+```typescript
+// postgresdk.config.ts
+export default {
+  connectionString: process.env.DATABASE_URL,
+  serverFramework: "hono",     // Hono is edge-compatible
+  useJsExtensions: true,        // Required for Vercel Edge
+  dateType: "string",           // Better for JSON serialization
+  auth: { apiKey: process.env.API_KEY }
+};
+```
+
+Server setup:
+```typescript
+import { Hono } from "hono";
+import { Pool } from "@neondatabase/serverless";
+import { createRouter } from "./generated/server/router";
+
+const app = new Hono();
+
+// Neon's Pool is compatible with node-postgres
+const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+
+// Wire up the generated routes (Pool has the same query interface)
+const apiRouter = createRouter({ pg: pool });
+app.route("/", apiRouter);
+
+// Deploy to Vercel Edge
+export const config = { runtime: 'edge' };
+export default app;
+```
+
+### Which Driver Should I Use?
+
+- **Use `pg` (default) when:**
+  - Running on traditional Node.js servers
+  - Using Docker, VPS, or dedicated hosting
+  - Need connection pooling or advanced PostgreSQL features
+  - Running on AWS Lambda, Google Cloud Functions (with Node.js runtime)
+
+- **Use `neon` when:**
+  - Deploying to Vercel Edge Functions
+  - Deploying to Cloudflare Workers
+  - Need globally distributed edge computing
+  - Want to avoid TCP connection overhead
+  - Using Neon as your PostgreSQL provider
+
+### Connection Pooling with `pg`
+
+For production Node.js deployments, use connection pooling:
+
+```typescript
+import { Pool } from "pg";
+import { createRouter } from "./generated/server/router";
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+
+// The generated routes work with both Client and Pool
+const apiRouter = createRouter({ pg: pool });
+```
+
+### Custom Database Adapters
+
+You can use any database client as long as it matches the expected interface:
+
+```typescript
+// Any client that implements this interface works
+interface DatabaseAdapter {
+  query(text: string, params?: any[]): Promise<{ rows: any[] }>;
+}
+
+// Both pg and @neondatabase/serverless Pool/Client implement this interface natively
+// For other ORMs, you may need to create an adapter:
+
+// Example with a hypothetical ORM that doesn't match the interface
+const customClient = new SomeORM();
+const pg = {
+  async query(text: string, params?: any[]) {
+    const result = await customClient.raw(text, params);
+    return { rows: result };
+  }
+};
+
+const apiRouter = createRouter({ pg });
+```
+
 ## Server Integration with Hono
 
 The generated code integrates seamlessly with [Hono](https://hono.dev/), a lightweight web framework for the Edge.