@vibeorm/adapter-pg 1.3.0 → 2.0.0-alpha.10

package/README.md

@@ -1,88 +1,96 @@
 # @vibeorm/adapter-pg
 
-`node-postgres` adapter for VibeORM. Use VibeORM with the `pg` driver on Bun or Node.js.
+> Part of **[VibeORM](https://github.com/vibeorm/vibeorm)** — a type-safe TypeScript ORM for Bun and Node. Prisma-schema or TypeScript-DSL input, a canonical schema IR, a generated client, and a dialect-aware SQL layer over PostgreSQL, PGlite, SQLite and MySQL.
 
-## Installation
+This adapter runs VibeORM on [node-postgres](https://node-postgres.com/) (`pg`) against a PostgreSQL server. It works on both Bun and Node, and `pg` is a peer dependency you install yourself.
 
 ```bash
-bun add @vibeorm/adapter-pg pg
+bun add @vibeorm/adapter-pg@alpha pg
 ```
 
+> **Pre-release.** `2.0.0-alpha.x`, published under the `alpha` dist-tag. `npm i vibeorm` still resolves to the stable v1 line.
+
 ## Usage
 
 ```ts
+import { VibeClient } from "./generated/vibeorm/index.js";
 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" }),
-});
+// connectionString defaults to process.env.DATABASE_URL
+const db = VibeClient({ adapter: pgAdapter({ connectionString: process.env.DATABASE_URL, max: 20 }) });
+
+const users = await db.user.findMany({ where: { email: { contains: "@example.com" } }, take: 10 });
+
+await db.$disconnect();
 ```
 
-### Using an existing pool
+To reuse a pool you already own, pass it in. The adapter never ends a pool it did not create, so `disconnect()` is a no-op in that mode:
 
 ```ts
 import pg from "pg";
-import { pgAdapter } from "@vibeorm/adapter-pg";
 
-const pool = new pg.Pool({ connectionString: "postgres://..." });
-
-const adapter = pgAdapter({ pool });
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+const db = VibeClient({ 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)
-  statementTimeout?: number;     // Default query timeout in ms (default: none)
-  connectionTimeout?: number;    // Max time to acquire a connection in ms (default: none)
-  preparedStatements?: boolean;  // Enable prepared statement caching (default: false)
-  stmtCacheMax?: number;         // Max cached prepared statements (default: 1000)
-};
-
-// Or use an existing pool (BYOP — you manage pool config)
-type PgAdapterOptions = {
-  pool: PgPool;                  // Existing pg.Pool instance
-  preparedStatements?: boolean;
-  stmtCacheMax?: number;
-};
-```
+`pgAdapter(options?: PgAdapterOptions)`:
 
-### Statement timeout
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `connectionString` | `string` | `process.env.DATABASE_URL` | PostgreSQL connection URL |
+| `pool` | `PgPoolLike` | — | An existing `pg.Pool` to use instead of creating one; it is never ended by the adapter |
+| `max` | `number` | `10` | Maximum pooled connections; ignored when `pool` is given |
+| `statementTimeout` | `number` (ms) | — | Pool-wide `statement_timeout`; a per-transaction `timeout` overrides it |
+| `connectionTimeout` | `number` (ms) | — | Wait for a pool checkout before failing (pg's `connectionTimeoutMillis`) |
+| `preparedStatements` | `boolean` | `false` | Send ORM-path queries as named prepared statements. Saves planning time, but PostgreSQL may fall back to a generic plan after ~5 executions — leave off unless profiling says otherwise |
+| `stmtCacheMax` | `number` | `1000` | Maximum entries in the prepared-statement name cache (LRU) |
 
-Set a default timeout for all queries. Any query exceeding this duration is cancelled by PostgreSQL (SQLSTATE `57014`), surfaced as a `VibeTransientError` with code `STATEMENT_TIMEOUT`.
+## Runtime support
 
-```ts
-const adapter = pgAdapter({
-  connectionString: "postgres://...",
-  statementTimeout: 30000, // 30 seconds
-});
-```
+| Runtime | Supported |
+|---|---|
+| Bun ≥ 1.2 | yes |
+| Node (with `pg` installed) | yes |
 
-Passed as `statement_timeout` in the pg Pool config, so every connection inherits it automatically with zero per-query overhead.
+`pg` is a pure-JavaScript driver, so nothing native has to build. Peer range: `pg >= 8`.
 
-Transaction-level `timeout` (via `db.$transaction(fn, { timeout })`) overrides this default for that transaction using `SET LOCAL statement_timeout`.
+## Capabilities
 
-> **Note:** `statementTimeout` and `connectionTimeout` are only available when creating a new pool. When you pass an existing `pool`, you manage these settings yourself via your pool config.
+This is a postgres-dialect adapter, so the full capability set is available: `RETURNING`, scalar array columns, native enums, `ILIKE`, `DISTINCT ON`, partial indexes, transactional DDL, `createManyAndReturn`, a real JSON column type, native `NULLS FIRST`/`NULLS LAST`, and the `"join"` relation strategy (`LEFT JOIN LATERAL` plus JSON aggregation). The generated capability table lives in [docs/dialects.md](https://github.com/vibeorm/vibeorm/blob/master/docs/dialects.md).
 
-### Connection timeout
+Transactions run on one checked-out client; nested `transaction()` calls become savepoints on that same client. Raw transaction control (`BEGIN` / `COMMIT` / `ROLLBACK` sent through the raw path, as `@vibeorm/migrate` does for transactional DDL) pins one client for the duration, so a raw transaction never splits across connections. Concurrent raw transactions on a single adapter are unsupported.
 
-Limit how long pool checkout (acquiring a connection) can take:
+## Parameter serialization: two paths
 
-```ts
-const adapter = pgAdapter({
-  connectionString: "postgres://...",
-  connectionTimeout: 5000, // 5 seconds
-});
-```
+`pg` turns a JS array into a PostgreSQL array literal natively, which is what a raw query wants but not what the ORM path can assume. The adapter therefore keeps two helpers:
+
+- `serializeParams` (ORM path): plain objects **and** plain arrays are JSON-stringified, since at that point they can only be `json`/`jsonb` values. Scalar-list values are tagged by `formatArrayParam` with `PgArrayParam` and unwrapped, reaching the driver as the untouched array.
+- `serializeParamsRaw` (raw path, `$queryRaw*` / `$executeRaw*` / DDL): plain JS arrays pass straight through, so `$queryRawUnsafe('… WHERE "id" = ANY($1)', [1, 2, 3])` matches rows. Binding an array *into* a `jsonb` column from a raw query means calling `JSON.stringify` yourself.
+
+## Error mapping
+
+Every driver failure becomes a `VibeError` with the driver error as `cause` and `meta` carrying `sqlstate` plus `constraint` / `table` / `column` when the server reported them. Table (`PG_SQLSTATE_ERROR_CODES`, frozen and mirrored by tests):
+
+| SQLSTATE | Condition | VibeError code | `meta.reason` |
+|---|---|---|---|
+| `23505` | unique_violation | `VIBE_UNIQUE_VIOLATION` | |
+| `23503` | foreign_key_violation | `VIBE_FK_VIOLATION` | |
+| `23502` | not_null_violation | `VIBE_VALIDATION` | |
+| `23514` | check_violation | `VIBE_VALIDATION` | |
+| `22P02` | invalid_text_representation | `VIBE_VALIDATION` | |
+| `40001` | serialization_failure | `VIBE_TRANSACTION` | |
+| `40P01` | deadlock_detected | `VIBE_TRANSACTION` | |
+| `57014` | query_canceled (statement_timeout) | `VIBE_TRANSACTION` | `"timeout"` |
+| anything else, including client-side failures such as `ECONNREFUSED` | | `VIBE_ADAPTER` | |
 
-Mapped to pg Pool's `connectionTimeoutMillis` option. Throws when the pool is exhausted and no connection becomes available within the limit.
+A `VibeError` raised deeper inside the ORM passes through unchanged.
 
-## License
+## Links
 
-[MIT](../../LICENSE)
+- [Documentation](https://github.com/vibeorm/vibeorm/tree/master/docs)
+- [Getting started](https://github.com/vibeorm/vibeorm/blob/master/docs/getting-started.md)
+- [Dialect capability tables](https://github.com/vibeorm/vibeorm/blob/master/docs/dialects.md)
+- [Repository and issues](https://github.com/vibeorm/vibeorm)
+- MIT licensed

package/dist/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Driver-error mapping for node-postgres (`pg`).
+ *
+ * Constitution rule 5: a raw driver error never escapes an adapter. Every
+ * failure becomes a `VibeError` with a stable code, the driver error attached
+ * as `cause`, and the SQLSTATE (plus constraint/table/column when the server
+ * reported them) in `meta`.
+ */
+import { VibeError, type VibeErrorCode } from "@vibeorm/schema";
+/**
+ * PostgreSQL SQLSTATE → stable VibeError code. Frozen and mirrored by tests;
+ * anything absent from this table maps to `VIBE_ADAPTER`.
+ */
+export declare const PG_SQLSTATE_ERROR_CODES: Readonly<Record<string, VibeErrorCode>>;
+/** SQLSTATEs that additionally explain themselves through `meta.reason`. */
+export declare const PG_SQLSTATE_REASONS: Readonly<Record<string, string>>;
+/**
+ * Extract the SQLSTATE from a pg driver error. `pg` puts the server's SQLSTATE
+ * on `error.code`; client-side failures (`ECONNREFUSED`, `ETIMEDOUT`, …) use
+ * the same field for a non-SQLSTATE string, which this rejects.
+ */
+export declare function pgErrorSqlstate(params: {
+    error: unknown;
+}): string | undefined;
+/**
+ * Map any error thrown by `pg` onto a `VibeError`.
+ *
+ * A `VibeError` passes through unchanged, so an error raised deeper inside the
+ * ORM (or by a nested adapter call) is never re-wrapped.
+ */
+export declare function mapPgDriverError(params: {
+    error: unknown;
+}): VibeError;
+/** Run a driver call, mapping anything it throws onto a `VibeError`. */
+export declare function runMapped<T>(fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIhE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CA2B1E,CAAC;AAEH,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE/D,CAAC;AAYH;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CAK9E;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CA0BtE;AAED,wEAAwE;AACxE,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMnE"}

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @vibeorm/adapter-pg — node-postgres (`pg`) adapter for VibeORM v2.
+ *
+ * Runs on Bun and Node. Owns pooling, optional named prepared statements,
+ * transactions (nested → savepoints on the same client) and driver-error
+ * mapping. Only `VibeError` ever escapes.
+ */
+import type { DatabaseAdapter } from "@vibeorm/runtime";
+/** The single `pg` query form this adapter uses (config object, never overloads). */
+export type PgQueryConfig = {
+    readonly text: string;
+    readonly values?: unknown[];
+    readonly name?: string;
+    /**
+     * QUERY-LOCAL result parsers ({@link EXACT_TYPES}). node-postgres reads this
+     * off the query config, so nothing outside VibeORM's own statements is
+     * affected — a caller's pool keeps the driver's documented behaviour.
+     */
+    readonly types?: PgTypeParsers;
+};
+/** The `pg-types` surface a query config may carry. */
+export type PgTypeParsers = {
+    getTypeParser(oid: number, format?: "text" | "binary"): (value: string) => unknown;
+};
+/** The parts of a `pg` result this adapter reads. */
+export type PgQueryResultLike = {
+    readonly rows: Record<string, unknown>[];
+    readonly rowCount: number | null;
+};
+/** The parts of a `pg` PoolClient this adapter uses. */
+export type PgPoolClientLike = {
+    query(config: PgQueryConfig): Promise<PgQueryResultLike>;
+    /**
+     * Hand the client back. A TRUTHY argument tells node-postgres to DESTROY it
+     * instead of pooling it — used when a rollback failed and the session state
+     * can no longer be asserted (EPIC 6). Optional so existing test doubles that
+     * declare `release(): void` still satisfy this type.
+     */
+    release(destroy?: boolean): void;
+    /**
+     * EventEmitter surface. A real `pg.PoolClient` has it; test doubles need not,
+     * so both members are optional and the adapter feature-detects them.
+     */
+    on?(event: "error", listener: (error: unknown) => void): void;
+    removeListener?(event: "error", listener: (error: unknown) => void): void;
+};
+/** The parts of a `pg` Pool this adapter uses — satisfied by a real `pg.Pool`. */
+export type PgPoolLike = {
+    connect(): Promise<PgPoolClientLike>;
+    query(config: PgQueryConfig): Promise<PgQueryResultLike>;
+    end(): Promise<void>;
+    /** EventEmitter surface; optional for the same reason as on {@link PgPoolClientLike}. */
+    on?(event: "error", listener: (error: unknown, client: PgPoolClientLike) => void): void;
+};
+/**
+ * Options for {@link pgAdapter}. Either point it at a connection string (the
+ * adapter then owns the pool it creates) or hand it a pool you already own.
+ */
+export type PgAdapterOptions = {
+    /** PostgreSQL connection URL. Defaults to `process.env.DATABASE_URL`. */
+    readonly connectionString?: string;
+    /**
+     * An existing `pg.Pool` to use instead of creating one. The adapter never
+     * ends a pool it did not create, so `disconnect()` is a no-op in this mode.
+     */
+    readonly pool?: PgPoolLike;
+    /** Maximum pooled connections (default 10). Ignored when `pool` is given. */
+    readonly max?: number;
+    /**
+     * Pool-wide `statement_timeout` in milliseconds. Every connection inherits
+     * it; a per-transaction `timeout` overrides it for that transaction.
+     */
+    readonly statementTimeout?: number;
+    /** Milliseconds to wait for a pool checkout before failing (pg's `connectionTimeoutMillis`). */
+    readonly connectionTimeout?: number;
+    /**
+     * Send ORM-path queries as named prepared statements (default false).
+     * Named statements save planning time but let PostgreSQL fall back to a
+     * generic plan after ~5 executions, which can pick worse indexes for range
+     * filters — leave off unless profiling says otherwise.
+     */
+    readonly preparedStatements?: boolean;
+    /** Maximum entries in the prepared-statement name cache (default 1000, LRU). */
+    readonly stmtCacheMax?: number;
+};
+/**
+ * Create a VibeORM adapter backed by node-postgres.
+ *
+ * @example
+ * ```ts
+ * const adapter = pgAdapter({ connectionString: process.env.DATABASE_URL, max: 20 });
+ * await adapter.connect();
+ * const rows = await adapter.execute({ text: 'SELECT * FROM "User" WHERE "id" = $1', values: [1] });
+ * ```
+ *
+ * @example Reusing a pool you already own
+ * ```ts
+ * import pg from "pg";
+ * const pool = new pg.Pool({ connectionString });
+ * const adapter = pgAdapter({ pool });
+ * ```
+ */
+export declare function pgAdapter(options?: PgAdapterOptions): DatabaseAdapter;
+export { PG_SQLSTATE_ERROR_CODES, PG_SQLSTATE_REASONS, mapPgDriverError, pgErrorSqlstate } from "./errors.ts";
+export { PgArrayParam, serializeParams, serializeParamsRaw } from "./params.ts";
+export { createSavepointCounter, nextSavepointName } from "./savepoints.ts";
+export type { SavepointCounter } from "./savepoints.ts";
+export { createStatementNameCache } from "./statement-cache.ts";
+export type { StatementNameCache } from "./statement-cache.ts";
+export { ISOLATION_LEVEL_SQL, beginStatement, classifyRawTransactionControl, refuseNestedTransactionOptions, statementTimeoutStatement, } from "./transaction-sql.ts";
+export type { RawTransactionControl } from "./transaction-sql.ts";
+export { DEFAULT_DEADLINE_CLOCK, engineStatementBudgetMs, isTransactionDeadlineError, startTransactionBudget, transactionClosedError, transactionDeadlineError, transactionOutcomeUnknownError, validateTransactionDeadline, } from "./transaction-budget.ts";
+export type { BudgetStage, DeadlineClock, TransactionBudget, TransactionOutcome } from "./transaction-budget.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}