@vibeorm/adapter-pg 4.3.0 → 5.0.0

package/README.md

@@ -41,19 +41,36 @@ const db = VibeClient({ adapter: pgAdapter({ pool }) });
 
 `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.
 
+**TLS with `sslrootcert=system`.** Managed providers such as PlanetScale hand out URLs ending in `?sslmode=verify-full&sslrootcert=system`. In libpq, `sslrootcert=system` means "trust the CA roots of the system"; node-postgres reads it as a file named `system` and fails with `ENOENT`. The adapter accepts it: the connection verifies the server certificate's chain and host name (`sslmode=verify-full`) against the runtime's default trust store — Node's bundled Mozilla roots plus `NODE_EXTRA_CA_CERTS`. To use the roots libpq itself would load, start Node with `--use-openssl-ca` (OpenSSL's default locations, honouring `SSL_CERT_FILE` / `SSL_CERT_DIR`), or with `--use-system-ca` for the operating system's store. As in libpq, an omitted `sslmode` means `verify-full`, and a weaker `sslmode` next to `sslrootcert=system` is refused at construction with `VIBE_CONFIG` (`meta.reason: "sslrootcert-system-weak-sslmode"`). `cancellationConnectionString` follows the same rule. A caller-supplied `pool` is configured by its owner: build it from the URL with `sslmode=verify-full` and without `sslrootcert=system`.
+
 | Option | Type | Default | Meaning |
 |---|---|---|---|
 | `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 |
+| `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. A pool-like object must return a distinct client object from `connect()` for each physical connection, never the same object for another one (`pg.Pool` does): native RLS `verify: "per-connection"` and `mode: "operator"` key their verdicts on it |
 | `max` | `number` | `10` | Maximum pooled connections; ignored when `pool` is given |
+| `min` | `number` | pg-pool's `0` | Connections the pool keeps open however long they sit idle (pg-pool's `min`). `db.$connect()` opens this many at once, so the first burst finds them warm (see [A database far away](#a-database-far-away)). An integer from `0` through `max`; other values throw `VIBE_CONFIG`. Refused with `VIBE_CONFIG` next to a caller-supplied `pool`: set `min` on that pool instead |
 | `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`) |
 | `idleTimeout` | `number` (ms) | pg-pool's `10000` | How long a pooled connection may sit idle before the pool closes it (pg's `idleTimeoutMillis`). Integer milliseconds from `0` through `2147483647`; other values throw `VIBE_CONFIG`. The next query after a quiet spell opens a new connection (TCP, startup, authentication — about 2.4 ms locally, more over TLS); a longer value, or `0` (never close), keeps connections open at the cost of held server connections. Ignored when `pool` is given |
 | `cancellationConnectionString` | `string` | Owned `connectionString`; none for an injected `pool` | Separate control endpoint for running read cancellation; same PostgreSQL server/database, with permission to signal the target role |
-| `preparedStatements` | `boolean` | `false` | Send ORM-path queries as named prepared statements. Measured −17…−25 % on reads and −6 % on a by-key update (see below). Off by default because of transaction-mode poolers — turn it on for direct connections, session pooling, or PgBouncer 1.21+ with `max_prepared_statements > 0` |
+| `preparedStatements` | `boolean` | `false` | Send ORM-path queries as named prepared statements. Measured −17…−25 % on reads and −6 % on a by-key update (see below). Off by default because of transaction-mode poolers — turn it on for direct connections, session pooling, or PgBouncer 1.21+ with `max_prepared_statements > 0`. Works with an injected `pool` too; the name budget (`stmtCacheMax`) then belongs to that pool and is shared by every adapter on it |
 | `stmtCacheMax` | `number` | `1000` | Budget of prepared-statement names per pool. Names never evict (an evicted name stays prepared on the backend), so this bounds server-side retention per connection; a text arriving after the budget is spent runs unnamed |
 | `planCacheMode` | `"auto" \| "force_custom_plan" \| "force_generic_plan"` | `"auto"` | PostgreSQL `plan_cache_mode` for every connection of the pool the adapter builds; sent in the `options` startup parameter, merged with an `options` the URL already carries (a URL that sets `plan_cache_mode` itself wins). Refused with `VIBE_CONFIG` next to a caller-supplied `pool` |
 
+### A database far away
+
+A new connection costs TCP, the startup message and authentication: about **three round trips** before the first query, more with TLS. On a local database that is noise (≈ 2.4 ms); across a network it is not. The framework team's report measured three parallel `findUnique` calls at 35 ms per round trip: **150 ms on a cold pool, 37 ms on a warm one** — the cold pool opened three connections first.
+
+- Keep connections open: set `idleTimeout` long, or `0` (never close an idle connection). pg-pool's default closes a connection after 10 s idle, so the first query after a quiet spell pays the connect again.
+- Keep a floor: `min: 3` keeps three connections open however long they idle.
+- Warm up at start: `await db.$connect()` opens `min` connections at once (at least one) and returns them to the pool, so the first burst does not pay for them.
+- With your own `pool`, set `min` and `idleTimeoutMillis` on that `pg.Pool`; the adapter's `min` is refused there, and `$connect()` opens one connection of it.
+
+```ts
+const db = VibeClient({ adapter: pgAdapter({ connectionString, max: 10, min: 3, idleTimeout: 0 }) });
+await db.$connect(); // three connections open before the first request
+```
+
 ### Prepared statements: the measured trade
 
 Interleaved rounds on this repository's benchmark database (postgres 16, `apps/benchmark/scratch/probe-join-agg.ts`, p50 of 7 rounds):
@@ -104,7 +121,9 @@ The timings above are historical measurements, not a schema-recovery or current
 
 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).
 
-Transactions run on one checked-out client; nested `transaction()` calls become savepoints on that same client. Statements issued at the same time on one transaction (`Promise.all` on a transaction handle, a statement the callback did not await) wait in the adapter's own queue and reach node-postgres one at a time, in the order they were issued: the adapter never calls `client.query()` while that client still runs a query (node-postgres' own queue for such calls is deprecated and goes away in pg@9). The top-level transaction handle of a transaction without a `deadline` or a `timeout`, on a client without a local `query_timeout`, and the savepoint handles it opens (a nested `tx.$transaction([...])`), declare `orderedPipeline`: the array form of `$transaction` then sends a count-only write (`createMany`, `updateMany`, `deleteMany`, `upsertMany` as one statement) and the next operation's first statement in one round trip — `[deleteMany, createMany, updateMany]` costs 2 round trips instead of 4 — and still sends `COMMIT` alone. Its lanes keep lane order, never send a statement behind a lane that closed without issuing one, and never send anything behind a failed statement, also when that failure had no server answer (no SQLSTATE `25P02` ever reaches a caller); see `DatabaseAdapter.pipeline` and [Transactions](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md#transactions) for what a caller can observe. Inside a transaction, raw SQL without bound values that is provably ONE statement (no `;`, no `$`, no comment, not transaction control and not `COPY`) travels with a pending `BEGIN` or `SAVEPOINT` like a bound statement, so a framework's `SELECT set_config('lock_timeout', '5000', true)` no longer costs a round trip of its own; raw SQL that may hold several statements keeps its own round trip. 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.
+Transactions run on one checked-out client; nested `transaction()` calls become savepoints on that same client. Statements issued at the same time on one transaction (`Promise.all` on a transaction handle, a statement the callback did not await) wait in the adapter's own queue and reach node-postgres one at a time, in the order they were issued: the adapter never calls `client.query()` while that client still runs a query (node-postgres' own queue for such calls is deprecated and goes away in pg@9). When the statement in flight returns, every statement that waited for it leaves as ONE batch (one Sync), in the order issued: a callback whose whole body is `Promise.all` of three creates costs 3 round trips instead of 4. Nothing waits for more statements to arrive — a statement issued while nothing runs goes at once, and a single waiting statement goes alone, as before. Not under a `deadline`, on a client with a local `query_timeout`, behind a read with `cancellation: "running"`, or for raw SQL that may hold several statements (it keeps its own round trip, and what was issued after it waits for it). A statement that fails on the server rejects with its own error; the statements the server skipped behind it in the same batch, and two or more statements still waiting when it failed, get the aborted-transaction refusal and never run (a single waiting statement is still sent, as before). The top-level transaction handle of a transaction without a `deadline`, on a client without a local `query_timeout`, and the savepoint handles it opens (a nested `tx.$transaction([...])`), declare `orderedPipeline` — also under a `timeout`, which is only the server's `SET LOCAL statement_timeout` and is applied to every statement of a batch on its own: the array form of `$transaction` then sends a count-only write (`createMany`, `updateMany`, `deleteMany`, `upsertMany` as one statement) and the next operation's first statement in one round trip, and `COMMIT` travels with the last statement when the last operation is such a write — `[deleteMany, createMany, updateMany]` costs 1 round trip instead of 4, with or without a `timeout`. Otherwise `COMMIT` is sent alone after the last operation settled; the callback form can end with one statement of your own and `COMMIT` in one round trip through the `commitWith` option (see [COMMIT travels with the last statement](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md#transactions)). Its lanes keep lane order, never send a statement behind a lane that closed without issuing one, and never send anything behind a failed statement, also when that failure had no server answer (no SQLSTATE `25P02` ever reaches a caller); see `DatabaseAdapter.pipeline` and [Transactions](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md#transactions) for what a caller can observe. Inside a transaction, raw SQL without bound values that is provably ONE statement (no `;`, no `$`, no comment, not transaction control and not `COPY`) travels with a pending `BEGIN` or `SAVEPOINT` like a bound statement, so a framework's `SELECT set_config('lock_timeout', '5000', true)` no longer costs a round trip of its own; raw SQL that may hold several statements keeps its own round trip. 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.
+
+Outside transactions the adapter declares `connectionGroup` (when the driver can batch and no local `query_timeout` is configured — the same conditions as `oneRoundTripTransactions`): the `"query"` strategy's sibling relation loads of one read leave together on ONE pooled connection as one batch (one Sync), so `findUnique` with three sibling includes costs 2 round trips instead of 4. The statements of one such batch run in one implicit transaction of the server: under `READ COMMITTED` each still reads its own snapshot, a statement that fails makes PostgreSQL skip the rest of its batch (the read rejects with the same first failure as before), and a server-side `transaction_timeout` (PostgreSQL 17+) covers the whole batch. A checked-out client that cannot batch is handed back unused and the statements go one after another. See [Sibling relation loads outside transactions](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md#sibling-relation-loads-outside-transactions-adapter-pg).
 
 A raw script that produces multiple PostgreSQL results returns only the **final command's** rows and affected-row count. Earlier results are not concatenated or summed; a final DDL command returns empty rows and zero affected rows.
 

package/dist/batch.d.ts

@@ -25,6 +25,12 @@
 export type BatchStep = {
     readonly text: string;
     readonly values?: readonly unknown[];
+    /**
+     * Nobody reads this step's rows (statement-count pass EPIC 5: the final
+     * statement that rides with COMMIT): they are not decoded, so no type parser
+     * can fail on them; the step reports no rows and its command tag's count.
+     */
+    readonly discardRows?: true;
 };
 /** A step's decoded result, shaped like the node-postgres result the adapter reads. */
 export type BatchStepResult = {
@@ -62,6 +68,8 @@ type RowDescriptionField = {
     readonly dataTypeID: number;
     readonly format?: "text" | "binary";
 };
+/** Whether this `pg` build exports what a one-Sync batch needs (`utils.prepareValue`); per-client checks stay in {@link supportsBatch}. */
+export declare function batchDriverAvailable(): boolean;
 /**
  * Whether `client` can run a one-Sync batch: a node-postgres client whose
  * connection exposes the protocol writers, NOT in pipeline mode (pipeline mode

package/dist/client-turns.d.ts

@@ -28,6 +28,16 @@ export type ClientTurns = {
     readonly run: <T>(send: () => Promise<T>) => Promise<T>;
     /** Calls handed in that have not settled yet (the running one included). */
     readonly outstanding: () => number;
+    /**
+     * The rejection of the call that settled LAST, or `undefined` when it
+     * fulfilled (or nothing settled yet). Read inside a turn, it is the outcome
+     * of the call right before it — already known there, before any of that
+     * call's own continuations ran (a burst of waiting statements reads it to
+     * refuse what the server would answer with 25P02).
+     */
+    readonly lastFailure: () => {
+        readonly error: unknown;
+    } | undefined;
 };
 /** Start the turn keeper for one checked-out client. */
 export declare function createClientTurns(): ClientTurns;

package/dist/connection-group.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Root connection groups (round-trip follow-up, lane A2;
+ * `DatabaseAdapter.connectionGroup`).
+ *
+ * A read's sibling relation loads outside any transaction: the runtime opens
+ * one sub-lane per statement, each sub-lane issues ONE statement, and once the
+ * group is sealed and every sub-lane issued or closed, the statements leave
+ * TOGETHER, in sub-lane order, on ONE pooled connection — one one-Sync batch
+ * (`./batch.ts`), so one round trip instead of one per sibling.
+ *
+ * This module is the group's bookkeeping only: the adapter hands it how to
+ * prepare a statement and how to send the prepared steps (checkout, batch,
+ * release — or one statement after another where the checked-out client cannot
+ * batch). Failure semantics are those of sequential dispatch in sub-lane
+ * order: a failed step's caller gets its mapped error; the steps PostgreSQL
+ * skipped behind it reject with the aborted refusal naming that failure.
+ */
+import { VibeError } from "@vibeorm/schema";
+import type { DatabaseAdapter, PipelineGroup } from "@vibeorm/runtime";
+import type { BatchOutcome, BatchStep } from "./batch.ts";
+/** The `execute` parameters a sub-lane receives (the root's `execute` contract). */
+export type ConnectionGroupExecute = Parameters<DatabaseAdapter["execute"]>[0];
+/** One statement of a group, ready to send: its batch step and the call it came from. */
+export type ConnectionGroupEntry = {
+    /** The step for the one-Sync batch (values already serialized for the driver). */
+    readonly step: BatchStep;
+    /** The sub-lane's original `execute` call (for a send that cannot batch: `root.execute`). */
+    readonly call: ConnectionGroupExecute;
+};
+/** What the adapter provides to a group. */
+export type ConnectionGroupDriver = {
+    /** The fields every sub-lane adapter carries (the root's declarations). */
+    readonly base: Pick<DatabaseAdapter, "dialect" | "provider" | "wire" | "budgets" | "roundTrips" | "formatArrayParam">;
+    /**
+     * Serialize one statement for the batch. A value the driver refuses throws
+     * (mapped): that sub-lane's call rejects with it and it holds nothing.
+     */
+    readonly prepare: (call: ConnectionGroupExecute) => BatchStep;
+    /**
+     * Send the group's statements, in order, as one round trip — or one after
+     * another where the checked-out connection cannot batch, reporting the
+     * statements after the first failure as skipped. Rejects only when nothing
+     * was sent (a failed checkout, a closed adapter): every statement then
+     * rejects with that error, mapped.
+     */
+    readonly send: (entries: readonly ConnectionGroupEntry[]) => Promise<BatchOutcome>;
+    /** Map a driver failure to the adapter's typed error. */
+    readonly mapError: (error: unknown) => VibeError;
+};
+/** A broken use of a connection group — a runtime defect, refused before anything is sent. */
+export declare function connectionGroupMisuse(params: {
+    message: string;
+}): VibeError;
+/**
+ * Open one connection group ({@link PipelineGroup}). Synchronous and free:
+ * nothing is checked out until the group is sealed and every sub-lane issued
+ * its statement or closed; a group that ends without a statement sends nothing.
+ */
+export declare function openConnectionGroup(params: {
+    driver: ConnectionGroupDriver;
+}): PipelineGroup;
+//# sourceMappingURL=connection-group.d.ts.map

package/dist/connection-string.d.ts

@@ -0,0 +1,55 @@
+/**
+ * libpq's `sslrootcert=system` for node-postgres.
+ *
+ * Managed PostgreSQL providers (PlanetScale, among others) hand out URLs such
+ * as `postgresql://…@host:5432/postgres?sslmode=verify-full&sslrootcert=system`.
+ * In libpq (PostgreSQL 16+) the value `system` means "load the trusted CA roots
+ * of the SSL implementation"; libpq then defaults `sslmode` to `verify-full`
+ * and refuses any weaker mode (libpq-connect, `sslrootcert`). node-postgres
+ * (pg 8.23 / pg-connection-string 2.14.1, the latest releases on 18.10.26, and
+ * its master branch) reads every `sslrootcert` as a FILE path —
+ * `fs.readFileSync("system")` — so the provider's URL fails before connecting
+ * with `ENOENT: no such file or directory, open 'system'`.
+ *
+ * {@link honourSystemRootCert} rewrites such a URL into node-postgres' own
+ * spelling of the same contract: `sslrootcert` removed, `sslmode=verify-full`.
+ * pg-connection-string then builds `ssl: {}` (plus any `sslcert`/`sslkey`),
+ * and `tls.connect` runs with its defaults: `rejectUnauthorized: true` (chain
+ * verified), the default `checkServerIdentity` against the host name
+ * node-postgres passes as `servername` (an IP address is matched against the
+ * certificate's IP entries, as in libpq), and — no `ca` given — the runtime's
+ * default trust store.
+ *
+ * "System roots" in that store: Node's default store is its bundled Mozilla
+ * root set (the program most operating-system stores derive from) plus
+ * `NODE_EXTRA_CA_CERTS`; started with `--use-openssl-ca` it loads OpenSSL's
+ * default locations, honouring `SSL_CERT_FILE` / `SSL_CERT_DIR` exactly as
+ * libpq-with-OpenSSL does, and with `--use-system-ca` the operating system's
+ * store. Bun's `node:tls` default is likewise its bundled root set plus
+ * `NODE_EXTRA_CA_CERTS`. The adapter passes no `ca`, so whichever of these the
+ * process chose applies — and connections reuse the runtime's parsed root
+ * store instead of re-parsing ~150 certificates per connection.
+ */
+/** The connection-string option a value came from, named in a refusal. */
+export type ConnectionStringOption = "connectionString" | "cancellationConnectionString";
+/**
+ * Rewrite a connection string carrying `sslrootcert=system` (libpq's "trust the
+ * system CA roots") into the form node-postgres understands: the parameter
+ * removed and `sslmode=verify-full` set, so the server certificate's chain and
+ * host name are both verified against the runtime's default trust store (see
+ * the module header). Any other string — no query, another `sslrootcert`, no
+ * `sslrootcert` — is returned byte-for-byte unchanged.
+ *
+ * Follows libpq's rule: with `system`, an omitted `sslmode` means
+ * `verify-full`, and every weaker mode is an error. node-postgres' own weaker
+ * spellings count too: `sslmode=no-verify`, and an `ssl` parameter other than
+ * `true` / `1`.
+ *
+ * @throws VibeError `VIBE_CONFIG` (`meta.reason: "sslrootcert-system-weak-sslmode"`)
+ * for a weaker mode. Neither the message nor `meta` carries the URL.
+ */
+export declare function honourSystemRootCert(params: {
+    connectionString: string;
+    option: ConnectionStringOption;
+}): string;
+//# sourceMappingURL=connection-string.d.ts.map

package/dist/index.d.ts

@@ -78,6 +78,11 @@ export type PgAdapterSettings = {
      * 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.
+     *
+     * libpq's `sslrootcert=system` (as in PlanetScale's URLs) is accepted:
+     * the adapter verifies the server certificate's chain and host name against
+     * the runtime's default trust store (`sslmode=verify-full`), and refuses a
+     * weaker `sslmode` next to it with `VIBE_CONFIG`, as libpq does.
      */
     readonly connectionString?: string;
     /**
@@ -85,10 +90,26 @@ export type PgAdapterSettings = {
      * 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.
+     *
+     * `connect()` must return a distinct client object for each physical
+     * connection and never hand the same object out for another one (node-postgres
+     * `pg.Pool` does: a `Client` never reconnects). The returned object is the
+     * transaction's `connectionIdentity`, which native-RLS per-connection
+     * verdicts and the operator login check are keyed on.
      */
     readonly pool?: PgPoolLike;
     /** Maximum pooled connections (default 10). Ignored when `pool` is given. */
     readonly max?: number;
+    /**
+     * Connections the pool keeps open however long they sit idle (pg-pool's
+     * `min`; default 0). `adapter.connect()` (`db.$connect()`) opens this many
+     * at once, so a burst of parallel queries finds them warm instead of paying
+     * TCP + startup + authentication per connection — about three round trips
+     * each, more with TLS. Must be an integer from 0 through `max`, else the
+     * factory throws `VIBE_CONFIG`. Refused next to `pool` (`VIBE_CONFIG`): the
+     * adapter cannot change a caller's pool — set `min` on that pool instead.
+     */
+    readonly min?: number;
     /**
      * Pool-wide `statement_timeout` in milliseconds. Every connection inherits
      * it; a per-transaction `timeout` overrides it for that transaction.