@vibeorm/adapter-pg 4.2.0 → 5.0.0

package/README.md

@@ -41,18 +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 and session pooling |
+| `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):
@@ -68,7 +86,17 @@ The saving is the server's parse/analyze and the protocol Parse/Describe round o
 
 A name is allocated on a text's **second** sighting, never its first: statement names never evict (an evicted name stays prepared on every backend that saw it), so first-sight allocation let a stream of one-off texts — offset pagination emits a distinct text per page — spend the whole `stmtCacheMax` budget for the pool's lifetime and leave the genuinely hot statements unnamed. A repeated statement therefore runs unprepared exactly once; a one-off statement costs the server nothing.
 
-Why it stays opt-in: named statements live on the **backend** connection. Behind a transaction-mode pooler (PgBouncer, Supavisor, Neon's pooler) that is not configured for protocol-level prepared statements, a client that remembers a statement name from an earlier transaction is handed a different backend later. The outcomes are SQLSTATE `26000` (statement missing), `42P05` (name collision on Parse) or — the one no error reveals — another client's statement executed under the same `vibeorm_N` name when its parameter types happen to be compatible. Enable it only where every connection maps to one backend for the process lifetime.
+**Statement names are collision-resistant.** A name is `vibeorm_` followed by the SHA-256 of the exact statement text in lowercase base32 (60 bytes, inside PostgreSQL's 63-byte identifier limit). The same text gets the same name in every pool, process and adapter version, and two different texts get the same name only if SHA-256 collides. So when a client reaches a backend that another pool prepared, a name can only stand for its own text: the outcome is the correct rows or an error, never another statement's rows (pinned in `tests/prepared-backend-switch.live.test.ts`). Before this change names were counters (`vibeorm_0`, `vibeorm_1`, …), and two independent pools could mean different texts by one name.
+
+Why it stays opt-in: named statements live on the **backend** connection, and node-postgres sends only Bind/Execute for a name it has parsed before. Supported setups:
+
+- a direct connection;
+- session pooling (each client keeps one backend for the session);
+- PgBouncer 1.21 or later in transaction mode with `max_prepared_statements` above 0, which prepares each statement on the backend it links the client to.
+
+Behind any other transaction-mode pooler (PgBouncer before 1.21 or with `max_prepared_statements = 0`, Supavisor, Neon's pooler) a client that remembers a name from an earlier transaction can be handed a different backend. The query then fails with SQLSTATE `26000` (the backend does not know the name) or `42P05` (the backend already holds the name on Parse). Both are `VIBE_ADAPTER` errors whose message ends with a hint about these setups, and the adapter discards that connection; no statement is retried. Turn `preparedStatements` off there.
+
+One case stays silent with every naming scheme: a statement prepared before DDL **shadows** a table. If a migration creates a table with the same name in a schema that comes earlier in the unchanged `search_path`, the prepared statement keeps reading the table it was parsed against until the connection is recycled. (A changed `search_path` itself is safe: PostgreSQL re-parses the statement.) Recycle connections after such a migration, as for the result-shape changes below.
 
 ### Schema changes with prepared statements
 
@@ -93,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. 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.
 
@@ -106,7 +136,7 @@ A raw script that produces multiple PostgreSQL results returns only the **final
 
 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".
+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` keeps pg-types' instants. The same per-query parsers decode the plain wire form of `timestamptz`, `timestamp` and `date` (`YYYY-MM-DD HH:MM:SS[.ffffff][±HH[:MM]]`, years 1000–9999) by character codes, about 3× cheaper per cell, and hand every other text (infinity, BC, earlier years, seconds offsets) to the parser that decoded it before; an application that registered its own global `timestamptz` parser through `pg.types` keeps it. See `docs/dialect-notes.md` "DateTime without time zone on postgres".
 
 ## Caller cancellation of reads
 

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

@@ -0,0 +1,44 @@
+/**
+ * One query at a time on a transaction's checked-out client (pg@9).
+ *
+ * node-postgres 8 queues a `client.query()` made while the client still runs
+ * another one, and warns that this queue goes away in pg@9.0 ("Calling
+ * client.query() when the client is already executing a query is deprecated
+ * and will be removed in pg@9.0"). A transaction handle receives statements
+ * concurrently — `Promise.all` on a callback-transaction handle, an un-awaited
+ * call, a ROLLBACK behind a failed batch — so the adapter keeps that queue
+ * itself: every call waits until the previous one SETTLED (the `await` pattern
+ * node-postgres documents), and the calls reach the client in the order they
+ * were made — the order the driver's own queue used. A call made while nothing
+ * is outstanding reaches the client synchronously, as before.
+ *
+ * "Settled" is the driver's own promise (or a batch's `done`): on success it
+ * settles at the statement's ReadyForQuery, so the next call finds the client
+ * idle; after a server error it settles at the ErrorResponse, and the next call
+ * waits inside node-postgres for that ReadyForQuery alone — never behind a
+ * second queued query.
+ */
+/** The turn keeper of ONE checked-out client. */
+export type ClientTurns = {
+    /**
+     * Run `send` (one `client.query()` call, or one batch) once every earlier
+     * call of this client settled. Resolves or rejects with `send`'s own
+     * outcome; a synchronous throw of `send` becomes its rejection.
+     */
+    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;
+//# sourceMappingURL=client-turns.d.ts.map

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/errors.d.ts

@@ -14,6 +14,14 @@ import { VibeError, type VibeErrorCode } from "@vibeorm/schema";
 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>>;
+/**
+ * SQLSTATEs whose message gets a remedy appended. The code stays what the
+ * SQLSTATE table says (`VIBE_ADAPTER` for both); only the human-readable text
+ * grows. Frozen and mirrored by tests. `0A000` ("cached plan must not change
+ * result type") is deliberately absent: it is the generic feature_not_supported
+ * class, so a prepared-statement hint would mislead on its other causes.
+ */
+export declare const PG_SQLSTATE_HINTS: 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

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.
@@ -96,6 +117,18 @@ export type PgAdapterSettings = {
     readonly statementTimeout?: number;
     /** Milliseconds to wait for a pool checkout before failing (pg's `connectionTimeoutMillis`). */
     readonly connectionTimeout?: number;
+    /**
+     * Milliseconds a pooled connection may sit idle before the pool closes it
+     * (pg-pool's `idleTimeoutMillis`). Unset keeps pg-pool's default of 10 000:
+     * the next query after a quiet spell then opens a new connection (TCP,
+     * startup, authentication — ≈ 2.4 ms locally, more over TLS). `0` keeps idle
+     * connections open until the server or network closes them; a longer value
+     * trades held server connections for fewer reconnects. Must be integer
+     * milliseconds from 0 through 2,147,483,647, else the factory throws
+     * `VIBE_CONFIG`. Ignored when
+     * `pool` is given: set `idleTimeoutMillis` on that pool.
+     */
+    readonly idleTimeout?: number;
     /** Separate direct/session-pinned PostgreSQL control endpoint for running reads.
      * Required with an injected pool; never inferred from that pool or ambient env.
      * The same role must be allowed to signal its target. Server support needs live acceptance.
@@ -112,11 +145,15 @@ export type PgAdapterSettings = {
      * picking worse indexes for range/LIKE/skewed filters).
      *
      * Off by default because named statements live on the BACKEND connection:
-     * behind a transaction-mode pooler (PgBouncer, Supavisor, Neon's pooler)
-     * without prepared-statement support a client that remembers a name from an
-     * earlier transaction is handed another backend later — SQLSTATE 26000,
-     * 42P05, or, worst, another client's statement under the same name executed
-     * without any error. Turn it on for direct connections and session pooling.
+     * behind a transaction-mode pooler (PgBouncer before 1.21 or with
+     * `max_prepared_statements = 0`, Supavisor, Neon's pooler) a client that
+     * remembers a name from an earlier transaction is handed another backend
+     * later. Names are collision-resistant (`vibeorm_` + the SHA-256 of the exact
+     * text, see `statementNameFor`), so a name can only ever stand for its own
+     * text: the remaining failure is a typed `VIBE_ADAPTER` error (SQLSTATE 26000
+     * or 42P05), never another statement's rows. Turn it on for direct
+     * connections, session pooling, or PgBouncer 1.21+ with
+     * `max_prepared_statements > 0`.
      *
      * Schema changes can invalidate a retained result descriptor (SQLSTATE
      * 0A000). No statement or transaction callback is retried. Drain traffic and