@vibeorm/adapter-pg 2.4.0 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeORM contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,31 +16,35 @@ bun add @vibeorm/adapter-pg pg
 import { VibeClient } from "./generated/vibeorm/index.js";
 import { pgAdapter } from "@vibeorm/adapter-pg";
 
-// connectionString defaults to process.env.DATABASE_URL
-const db = VibeClient({ adapter: pgAdapter({ connectionString: process.env.DATABASE_URL, max: 20 }) });
+// The adapter reads no environment variable: pass the address you mean.
+const connectionString = process.env.DATABASE_URL;
+if (!connectionString) throw new Error("DATABASE_URL is not set");
+const db = VibeClient({ adapter: pgAdapter({ connectionString, max: 20 }) });
 
 const users = await db.user.findMany({ where: { email: { contains: "@example.com" } }, take: 10 });
 
 await db.$disconnect();
 ```
 
-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:
+`disconnect()` ends the adapter for good: work that already started finishes, the pool it created is ended once, and every later call refuses with `VIBE_ADAPTER_CLOSED`. Create a new adapter to connect again.
+
+To reuse a pool you already own, pass it in. The adapter never ends a pool it did not create: in that mode `disconnect()` only ends the adapter, and the pool stays usable by its owner and by other adapters:
 
 ```ts
 import pg from "pg";
 
-const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+const pool = new pg.Pool({ connectionString });
 const db = VibeClient({ adapter: pgAdapter({ pool }) });
 ```
 
 ## Options
 
-`pgAdapter(options?: PgAdapterOptions)`:
+`pgAdapter(options: PgAdapterOptions)` — `connectionString` or `pool` is required. Without either, the factory throws `VIBE_CONFIG` (`meta.reason: "missing-address"`) before any pool or connection exists. The adapter never reads `DATABASE_URL`. Give a complete URL: node-postgres fills parts a URL leaves out (host, user, database, …) from the `PG*` environment variables.
 
 | 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 |
+| `connectionString` | `string` | — (required without `pool`) | PostgreSQL connection URL |
+| `pool` | `PgPoolLike` | — (required without `connectionString`) | An existing `pg.Pool` to use instead of creating one; it is never ended by the adapter, and it wins when both are given |
 | `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`) |
@@ -71,7 +75,7 @@ Why it stays opt-in: named statements live on the **backend** connection. Behind
 
 The adapter surfaces the failure as `VIBE_ADAPTER` with `meta.sqlstate: "0A000"` and the driver error as `cause`. It does not retry the statement, replay a transaction callback, or issue `DEALLOCATE`. Inside a transaction, the error leaves PostgreSQL in its aborted state until rollback. SQLSTATE `0A000` also covers other unsupported features, so it is not a safe generic retry signal.
 
-For an incompatible schema deployment, stop admitting work on the old pool, let active transactions settle, apply the migration, then recycle the connections before resuming traffic. If the adapter owns its pool, await `disconnect()` after draining and reconnect it, or create a new adapter. If you supplied `pool`, its owner must await `pool.end()` and supply a new pool to a new adapter. Disconnecting or replacing only the adapter leaves an injected pool's retained statements intact. Never run `DEALLOCATE ALL` behind node-postgres' remembered statement-name registry.
+For an incompatible schema deployment, stop admitting work on the old pool, let active transactions settle, apply the migration, then recycle the connections before resuming traffic. If the adapter owns its pool, await `disconnect()` after draining and create a new adapter (a disconnected adapter does not reconnect). If you supplied `pool`, its owner must await `pool.end()` and supply a new pool to a new adapter. Disconnecting or replacing only the adapter leaves an injected pool's retained statements intact. Never run `DEALLOCATE ALL` behind node-postgres' remembered statement-name registry.
 
 The timings above are historical measurements, not a schema-recovery or current performance guarantee. Prepared statements remain opt-in; applications without a coordinated connection lifecycle should keep the default `preparedStatements: false`.
 
@@ -99,7 +103,7 @@ A raw script that produces multiple PostgreSQL results returns only the **final
 - `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.
 
-A string bound to a `::jsonb` slot on the raw path is sent as text and parsed by the server, so pre-encoded JSON text stores the document here — on `@vibeorm/adapter-bun` the same statement stores a jsonb *string*, because bun:sql JSON-encodes whatever is bound to a jsonb slot. Spell the slot `::text::jsonb` when a raw statement must run on both drivers; that is what the ORM path renders for `Json` fields (pinned live in `tests/raw-jsonb.live.test.ts` on both adapters).
+A string bound to a `::jsonb` slot on the raw path is sent as text and parsed by the server, so pre-encoded JSON text stores the document here, and on `@vibeorm/adapter-bun` with its default unnamed statements. With adapter-bun's `preparedStatements: true` the same statement stores a jsonb *string*, because bun:sql then JSON-encodes whatever is bound to a jsonb slot. Spell the slot `::text::jsonb` when a raw statement must run on both drivers; that is what the ORM path renders for `Json` fields (pinned live in `tests/raw-jsonb.live.test.ts` on both adapters).
 
 On both paths a `Date` is spelled as UTC ISO text (`2026-03-08T19:38:08.538Z`) rather than node-postgres' host-local form, and the result side attaches per-query parsers (never `pg.types` globally) that read `timestamp without time zone`, `date` and their arrays as **UTC** — pg-types reads them as host-local time. Together they give zone-less columns (Prisma's `@db.Timestamp(n)` / `@db.Date`) the UTC wall-clock contract shared with bun:sql, PGlite and Prisma, whatever the process `TZ` is; `timestamptz` is unaffected. See `docs/dialect-notes.md` "DateTime without time zone on postgres".
 

package/dist/batch.d.ts

@@ -0,0 +1,152 @@
+/**
+ * One-Sync batch for node-postgres (round-trip EPIC 6, pipelining).
+ *
+ * Several statements go to the server as Parse / Bind / Describe / Execute
+ * each, followed by ONE Sync — one wait instead of one per statement. It is a
+ * `Submittable` (the extension point `client.query(object)` documents and
+ * pg-cursor uses) running on an ordinary, NON-pipeline client: the batch is one
+ * query object, so the client's own queue, ReadyForQuery handling and status
+ * bookkeeping stay node-postgres'.
+ *
+ * PostgreSQL's extended protocol skips every message after an error until the
+ * Sync (as libpq pipeline mode does), so a failing step leaves every later step
+ * UNRUN — a failed `BEGIN` can never let a later write run in autocommit, and
+ * no later step answers 25P02 (spike-report §1.3, "pg one-Sync batch").
+ *
+ * Only API that node-postgres exposes is used: `connection.parse / bind /
+ * describe / execute / sync` (declared on `Connection` in @types/pg), the
+ * message handlers of the Submittable contract, and the driver's own
+ * `utils.prepareValue` (a property of the `pg` module object, feature-detected)
+ * so parameters serialize exactly as `client.query` serializes them. Rows are
+ * decoded HERE, with the adapter's query-local type parsers — never through
+ * node-postgres' internal `lib/result.js`.
+ */
+/** One statement of a batch. Values are the adapter's already-serialized params. */
+export type BatchStep = {
+    readonly text: string;
+    readonly values?: readonly unknown[];
+};
+/** A step's decoded result, shaped like the node-postgres result the adapter reads. */
+export type BatchStepResult = {
+    readonly rows: Record<string, unknown>[];
+    readonly rowCount: number | null;
+    readonly command?: string;
+};
+/** Per-step outcome after the batch's ReadyForQuery. */
+export type BatchStepOutcome = {
+    readonly status: "ok";
+    readonly result: BatchStepResult;
+} | {
+    readonly status: "failed";
+    readonly error: unknown;
+} | {
+    readonly status: "skipped";
+};
+/** What a batch reports once it settled. */
+export type BatchOutcome = {
+    /** One entry per step, in order. */
+    readonly steps: readonly BatchStepOutcome[];
+    /**
+     * A failure WITHOUT a server answer — the socket broke, or the client's
+     * `query_timeout` fired while the batch was still on the wire. What the
+     * server did with the batch is unknown; `steps` lists only what was seen.
+     */
+    readonly transportError?: unknown;
+};
+/** The query-local type parser surface (the adapter's `EXACT_TYPES`). */
+export type BatchTypeParsers = {
+    getTypeParser(oid: number, format?: "text" | "binary"): (value: string) => unknown;
+};
+type RowDescriptionField = {
+    readonly name: string;
+    readonly dataTypeID: number;
+    readonly format?: "text" | "binary";
+};
+/**
+ * Whether `client` can run a one-Sync batch: a node-postgres client whose
+ * connection exposes the protocol writers, NOT in pipeline mode (pipeline mode
+ * sends a Sync per query and was rejected by the spike), with the driver's
+ * value serializer available. Test doubles and foreign clients answer false
+ * and keep today's one-statement-per-wait path.
+ */
+export declare function supportsBatch(params: {
+    client: unknown;
+}): boolean;
+/**
+ * Serialize a step's parameters with the driver's own `prepareValue`. Runs
+ * BEFORE anything is written, so a value the driver cannot serialize refuses
+ * the whole batch with nothing sent (node-postgres' own path closes and syncs
+ * instead; the caller-visible error is the same driver error).
+ */
+export declare function prepareBatchValues(params: {
+    values: readonly unknown[];
+}): unknown[];
+/**
+ * The Submittable. Construct with steps whose values are already prepared
+ * ({@link prepareBatchValues}); pass to `client.query(batch)`; await
+ * {@link PgBatch.done}.
+ */
+export declare class PgBatch {
+    /** Settles once: at the batch's ReadyForQuery, at its first server error, or at a transport failure. */
+    readonly done: Promise<BatchOutcome>;
+    /**
+     * Set by node-postgres when the client has a `query_timeout`: its wrapper
+     * clears the read-timeout timer. Called once when the batch settles, so a
+     * timer never outlives the batch (fix lane FX-A, RV5 MI-6).
+     */
+    callback: ((error: unknown, result?: unknown) => void) | undefined;
+    private readonly steps;
+    private readonly types;
+    private readonly outcomes;
+    private parsers;
+    private fields;
+    private rows;
+    /** The first type-parser failure of the current step; its remaining rows are skipped. */
+    private rowError;
+    private settled;
+    private resolve;
+    constructor(params: {
+        steps: readonly BatchStep[];
+        types: BatchTypeParsers;
+    });
+    /** Called by node-postgres when the batch reaches the head of the client's queue. */
+    submit(connection: unknown): void;
+    handleRowDescription(message: {
+        fields: readonly RowDescriptionField[];
+    }): void;
+    handleDataRow(message: {
+        fields: readonly (string | null)[];
+    }): void;
+    handleCommandComplete(message: {
+        text?: string;
+        command?: string;
+    }): void;
+    handleEmptyQuery(): void;
+    handleError(error: unknown): void;
+    handleReadyForQuery(): void;
+    handlePortalSuspended(): void;
+    handleCopyInResponse(connection: unknown): void;
+    handleCopyData(): void;
+    private finish;
+}
+/** Run `steps` as one batch on `client` and wait for it to settle. */
+export declare function runBatch(params: {
+    /** A checked-out client that passed {@link supportsBatch}. */
+    client: {
+        query: (...args: never[]) => unknown;
+    };
+    steps: readonly BatchStep[];
+    types: BatchTypeParsers;
+}): Promise<BatchOutcome>;
+/**
+ * The first failure of a settled batch: the transport error, or the first
+ * failed step with its index. `undefined` when every step succeeded.
+ */
+export declare function firstBatchFailure(params: {
+    outcome: BatchOutcome;
+}): {
+    readonly index: number;
+    readonly error: unknown;
+} | undefined;
+export {};
+//# sourceMappingURL=batch.d.ts.map

package/dist/index.d.ts

@@ -63,15 +63,22 @@ export type PgPoolLike = {
     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.
+ * Every {@link pgAdapter} option. {@link PgAdapterOptions} adds the rule that
+ * one of `connectionString` and `pool` is present.
  */
-export type PgAdapterOptions = {
-    /** PostgreSQL connection URL. Defaults to `process.env.DATABASE_URL`. */
+export type PgAdapterSettings = {
+    /**
+     * PostgreSQL connection URL. The adapter never reads `DATABASE_URL` (or any
+     * other environment variable) itself: pass the URL you mean. Give a complete
+     * URL — node-postgres fills parts the URL omits (host, user, database, …)
+     * from the `PG*` environment variables.
+     */
     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.
+     * ends a pool it did not create: `disconnect()` only ends this adapter (and
+     * rolls back and releases its own raw session); the pool stays usable.
+     * Wins over `connectionString` when both are given.
      */
     readonly pool?: PgPoolLike;
     /** Maximum pooled connections (default 10). Ignored when `pool` is given. */
@@ -130,12 +137,27 @@ export type PgAdapterOptions = {
      */
     readonly planCacheMode?: PlanCacheMode;
 };
+/**
+ * Options for {@link pgAdapter}: an explicit address is required. Either point
+ * it at a connection string (the adapter then owns the pool it creates) or hand
+ * it a pool you already own. Without either, the factory throws `VIBE_CONFIG`
+ * before any pool or connection exists.
+ */
+export type PgAdapterOptions = PgAdapterSettings & ({
+    readonly connectionString: string;
+} | {
+    readonly pool: PgPoolLike;
+});
 /**
  * Create a VibeORM adapter backed by node-postgres.
  *
+ * Requires an explicit address (`connectionString` or `pool`); see
+ * {@link PgAdapterOptions}. Construction opens nothing — the pool is created
+ * on first use.
+ *
  * @example
  * ```ts
- * const adapter = pgAdapter({ connectionString: process.env.DATABASE_URL, max: 20 });
+ * const adapter = pgAdapter({ connectionString: "postgresql://app:secret@db.internal:5432/app", max: 20 });
  * await adapter.connect();
  * const rows = await adapter.execute({ text: 'SELECT * FROM "User" WHERE "id" = $1', values: [1] });
  * ```
@@ -147,7 +169,7 @@ export type PgAdapterOptions = {
  * const adapter = pgAdapter({ pool });
  * ```
  */
-export declare function pgAdapter(options?: PgAdapterOptions): DatabaseAdapter;
+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 "@vibeorm/runtime/adapter-kit";