@vibeorm/adapter-pg 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# @vibeorm/adapter-pg
+
+`node-postgres` adapter for VibeORM. Use VibeORM with the `pg` driver on Bun or Node.js.
+
+## Installation
+
+```bash
+bun add @vibeorm/adapter-pg pg
+```
+
+## Usage
+
+```ts
+import { pgAdapter } from "@vibeorm/adapter-pg";
+import { VibeClient } from "./generated/vibeorm/index.ts";
+
+const db = VibeClient({
+  adapter: pgAdapter({ connectionString: "postgres://user:pass@localhost:5432/mydb" }),
+});
+```
+
+### Using an existing pool
+
+```ts
+import pg from "pg";
+import { pgAdapter } from "@vibeorm/adapter-pg";
+
+const pool = new pg.Pool({ connectionString: "postgres://..." });
+
+const adapter = pgAdapter({ pool });
+```
+
+When you pass an existing pool, the adapter will **not** call `pool.end()` on disconnect — you manage the pool lifecycle.
+
+## Options
+
+```ts
+// Create a new pool
+type PgAdapterOptions = {
+  connectionString?: string;     // Connection string (defaults to DATABASE_URL env)
+  max?: number;                  // Pool size (default: 10)
+  preparedStatements?: boolean;  // Enable prepared statement caching (default: false)
+  stmtCacheMax?: number;         // Max cached prepared statements (default: 1000)
+};
+
+// Or use an existing pool
+type PgAdapterOptions = {
+  pool: PgPool;                  // Existing pg.Pool instance
+  preparedStatements?: boolean;
+  stmtCacheMax?: number;
+};
+```
+
+## License
+
+[MIT](../../LICENSE)

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@vibeorm/adapter-pg",
+  "version": "1.0.0",
+  "description": "node-postgres adapter for VibeORM — use VibeORM with pg on Bun or Node.js",
+  "license": "MIT",
+  "keywords": [
+    "orm",
+    "adapter",
+    "pg",
+    "node-postgres",
+    "postgresql",
+    "typescript"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibeorm/vibeorm.git",
+    "directory": "packages/adapter-pg"
+  },
+  "homepage": "https://github.com/vibeorm/vibeorm/tree/master/packages/adapter-pg",
+  "bugs": {
+    "url": "https://github.com/vibeorm/vibeorm/issues"
+  },
+  "dependencies": {
+    "@vibeorm/runtime": "workspace:*"
+  },
+  "peerDependencies": {
+    "pg": ">=8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,325 @@
+/**
+ * @vibeorm/adapter-pg — node-postgres (pg) adapter for VibeORM.
+ *
+ * Uses the `pg` package's Pool for connection pooling with optional
+ * named prepared statement caching for PostgreSQL plan reuse.
+ */
+
+import type { DatabaseAdapter, QueryResult } from "@vibeorm/runtime";
+
+/**
+ * Options for creating a pg adapter.
+ * Either provide connection parameters or an existing Pool instance.
+ */
+export type PgAdapterOptions = {
+  /** PostgreSQL connection URL. Falls back to DATABASE_URL env var if not provided. */
+  connectionString?: string;
+  /** Maximum number of connections in the pool (default: 10). */
+  max?: number;
+  /**
+   * Whether to use named prepared statements for read queries (default: false).
+   *
+   * When `true`, the adapter assigns a deterministic name to each unique SQL text,
+   * creating named prepared statements that PostgreSQL caches execution plans for.
+   * This saves ~0.1ms of planning time per query but can cause PostgreSQL to
+   * switch to a "generic plan" after 5 executions, which may choose a worse
+   * index for queries with range filters or skewed data distributions.
+   *
+   * When `false` (default), the adapter sends queries without a statement name.
+   * PostgreSQL replans each execution using the actual parameter values, always
+   * choosing the optimal index.
+   *
+   * Recommendation: Leave as `false` unless profiling shows planning overhead
+   * is a bottleneck (rare — typically only for sub-millisecond queries at
+   * very high throughput).
+   */
+  preparedStatements?: boolean;
+  /**
+   * Maximum number of entries in the prepared statement name cache (default: 1000).
+   * Only used when `preparedStatements: true`.
+   * Each unique SQL text gets a deterministic name for PostgreSQL plan caching.
+   * LRU eviction when full.
+   */
+  stmtCacheMax?: number;
+} | {
+  /** An existing pg Pool instance to use. */
+  pool: PgPool;
+  /**
+   * Whether to use named prepared statements for read queries (default: false).
+   * See the other overload for full documentation.
+   */
+  preparedStatements?: boolean;
+  /**
+   * Maximum number of entries in the prepared statement name cache (default: 1000).
+   * Only used when `preparedStatements: true`.
+   */
+  stmtCacheMax?: number;
+};
+
+// ─── Minimal pg types (avoids hard dependency on @types/pg) ───────
+
+type PgPoolClient = {
+  query(config: { text: string; values?: unknown[]; name?: string }): Promise<PgQueryResult>;
+  query(text: string, values?: unknown[]): Promise<PgQueryResult>;
+  release(): void;
+};
+
+type PgQueryResult = {
+  rows: Record<string, unknown>[];
+  rowCount: number | null;
+  command: string;
+};
+
+type PgPool = {
+  connect(): Promise<PgPoolClient>;
+  query(config: { text: string; values?: unknown[]; name?: string }): Promise<PgQueryResult>;
+  query(text: string, values?: unknown[]): Promise<PgQueryResult>;
+  end(): Promise<void>;
+};
+
+// ─── Internal marker for array params ─────────────────────────────
+
+/**
+ * Internal wrapper to tag a value as a PostgreSQL array parameter (for = ANY()).
+ * This distinguishes array params from JSON array values so the adapter
+ * can JSON.stringify JSON values without affecting array params.
+ */
+class PgArrayParam {
+  constructor(public readonly values: unknown[]) {}
+}
+
+// ─── Value Serialization ──────────────────────────────────────────
+
+/**
+ * Pre-process query parameter values for the pg driver.
+ *
+ * The pg driver auto-converts JS arrays to PostgreSQL array literals (`{1,2,3}`)
+ * and JS objects to `[object Object]`. For json/jsonb columns, we need these
+ * serialized as JSON strings instead. Since the query builder is driver-agnostic
+ * and doesn't serialize values, we handle it here at the adapter boundary.
+ *
+ * - PgArrayParam wrappers are unwrapped to raw arrays (for = ANY() queries)
+ * - Plain objects and arrays are JSON.stringify'd (for json/jsonb columns)
+ * - Dates, Buffers, null, and primitives pass through unchanged
+ */
+function serializeParams(params: { values: unknown[] }): unknown[] {
+  return params.values.map((v) => {
+    // Unwrap tagged array params — these are for = ANY() and must remain as raw arrays
+    if (v instanceof PgArrayParam) {
+      return v.values;
+    }
+    // JSON.stringify plain objects and arrays for json/jsonb columns
+    if (
+      v !== null &&
+      v !== undefined &&
+      typeof v === "object" &&
+      !(v instanceof Date) &&
+      !Buffer.isBuffer(v) &&
+      !(v instanceof Uint8Array)
+    ) {
+      return JSON.stringify(v);
+    }
+    return v;
+  });
+}
+
+/**
+ * Create a VibeORM database adapter using node-postgres (pg).
+ *
+ * @example
+ * ```ts
+ * import { pgAdapter } from "@vibeorm/adapter-pg";
+ * import { VibeClient } from "./generated/vibeorm";
+ *
+ * // With connection string
+ * const db = VibeClient({
+ *   adapter: pgAdapter({ connectionString: "postgres://...", max: 20 }),
+ * });
+ *
+ * // With existing pg Pool
+ * import { Pool } from "pg";
+ * const pool = new Pool({ connectionString: "postgres://..." });
+ * const db = VibeClient({
+ *   adapter: pgAdapter({ pool }),
+ * });
+ *
+ * // With prepared statements enabled (for high-throughput local scenarios)
+ * const db2 = VibeClient({
+ *   adapter: pgAdapter({ connectionString: "postgres://...", preparedStatements: true }),
+ * });
+ * ```
+ */
+export function pgAdapter(options?: PgAdapterOptions): DatabaseAdapter {
+  const USE_PREPARED = (options && "preparedStatements" in options ? options.preparedStatements : undefined) ?? false;
+  const stmtCacheMax = (options && "stmtCacheMax" in options ? options.stmtCacheMax : undefined) ?? 1000;
+
+  // LRU cache: SQL text -> deterministic prepared statement name
+  const stmtNameCache = new Map<string, string>();
+  let stmtCounter = 0;
+
+  function getOrCreateStmtName(params: { text: string }): string {
+    const { text } = params;
+    let name = stmtNameCache.get(text);
+    if (name) {
+      // Move to end (most recently used)
+      stmtNameCache.delete(text);
+      stmtNameCache.set(text, name);
+      return name;
+    }
+    name = `vibeorm_${stmtCounter++}`;
+    if (stmtNameCache.size >= stmtCacheMax) {
+      const oldestKey = stmtNameCache.keys().next().value;
+      if (oldestKey !== undefined) stmtNameCache.delete(oldestKey);
+    }
+    stmtNameCache.set(text, name);
+    return name;
+  }
+
+  let pool: PgPool | null = null;
+  let ownsPool = false;
+
+  function getPool(): PgPool {
+    if (pool) return pool;
+
+    // Dynamic import of pg to avoid bundling issues
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const pg = require("pg");
+    const Pool = pg.Pool ?? pg.default?.Pool;
+
+    if (options && "pool" in options && options.pool) {
+      pool = options.pool;
+      ownsPool = false;
+    } else {
+      const connectionString =
+        (options && "connectionString" in options ? options.connectionString : undefined) ??
+        process.env.DATABASE_URL;
+      const max = (options && "max" in options ? options.max : undefined) ?? 10;
+
+      pool = new Pool({
+        connectionString,
+        max,
+      }) as PgPool;
+      ownsPool = true;
+    }
+
+    return pool;
+  }
+
+  /**
+   * Execute a parameterized query through a pg client or pool.
+   * - preparedStatements=true: uses named statements for plan caching
+   * - preparedStatements=false: uses unnamed statements (replanned each time)
+   */
+  function buildQueryConfig(params: { text: string; values: unknown[] }): { text: string; values: unknown[]; name?: string } {
+    const serialized = serializeParams({ values: params.values });
+    if (USE_PREPARED) {
+      return {
+        name: getOrCreateStmtName({ text: params.text }),
+        text: params.text,
+        values: serialized,
+      };
+    }
+    return {
+      text: params.text,
+      values: serialized,
+    };
+  }
+
+  function createClientAdapter(client: PgPoolClient): DatabaseAdapter {
+    return {
+      async execute(params) {
+        const config = buildQueryConfig(params);
+        const result = await client.query(config);
+        return result.rows;
+      },
+
+      async executeUnsafe(params) {
+        const values = params.values ? serializeParams({ values: params.values }) : undefined;
+        const result = await client.query(params.text, values);
+        const affectedRows = result.rowCount ?? 0;
+        return { rows: result.rows, affectedRows };
+      },
+
+      async transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>): Promise<T> {
+        // Nested transactions use SAVEPOINTs
+        await client.query("SAVEPOINT vibeorm_nested");
+        try {
+          const nestedAdapter = createClientAdapter(client);
+          const result = await fn(nestedAdapter);
+          await client.query("RELEASE SAVEPOINT vibeorm_nested");
+          return result;
+        } catch (err) {
+          await client.query("ROLLBACK TO SAVEPOINT vibeorm_nested");
+          throw err;
+        }
+      },
+
+      async connect() {
+        // No-op for client-level adapter (already connected)
+      },
+
+      async disconnect() {
+        // No-op for client-level adapter (pool manages connections)
+      },
+
+      formatArrayParam(values: unknown[]): unknown {
+        // Wrap in PgArrayParam so serializeParams knows not to JSON.stringify it
+        return new PgArrayParam(values);
+      },
+    };
+  }
+
+  const adapter: DatabaseAdapter = {
+    async execute(params) {
+      const p = getPool();
+      const config = buildQueryConfig(params);
+      const result = await p.query(config);
+      return result.rows;
+    },
+
+    async executeUnsafe(params) {
+      const p = getPool();
+      const values = params.values ? serializeParams({ values: params.values }) : undefined;
+      const result = await p.query(params.text, values);
+      const affectedRows = result.rowCount ?? 0;
+      return { rows: result.rows, affectedRows };
+    },
+
+    async transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>): Promise<T> {
+      const p = getPool();
+      const client = await p.connect();
+      try {
+        await client.query("BEGIN");
+        const txAdapter = createClientAdapter(client);
+        const result = await fn(txAdapter);
+        await client.query("COMMIT");
+        return result;
+      } catch (err) {
+        await client.query("ROLLBACK");
+        throw err;
+      } finally {
+        client.release();
+      }
+    },
+
+    async connect() {
+      const p = getPool();
+      const client = await p.connect();
+      client.release();
+    },
+
+    async disconnect() {
+      if (pool && ownsPool) {
+        await pool.end();
+        pool = null;
+      }
+    },
+
+    formatArrayParam(values: unknown[]): unknown {
+      // Wrap in PgArrayParam so serializeParams knows not to JSON.stringify it
+      return new PgArrayParam(values);
+    },
+  };
+
+  return adapter;
+}