@vibeorm/adapter-pg 2.0.0 → 2.0.2

package/README.md

@@ -44,8 +44,24 @@ const db = VibeClient({ adapter: pgAdapter({ pool }) });
 | `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 |
+| `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 |
 | `stmtCacheMax` | `number` | `1000` | Maximum entries in the prepared-statement name cache (LRU) |
+| `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` |
+
+### 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):
+
+| shape | unnamed (default) | `preparedStatements: true` | + `planCacheMode: "force_custom_plan"` |
+|---|---|---|---|
+| findUnique × 10 | 1.28 ms | 1.01 ms (−21 %) | 1.06 ms (−17 %) |
+| findMany where + orderBy + take | 0.175 ms | 0.143 ms (−18 %) | 0.144 ms (−18 %) |
+| update by primary key | 0.82 ms | 0.77 ms (−6 %) | 0.76 ms (−8 %) |
+| findMany + include (take 50) | 0.52 ms | 0.42 ms (−20 %) | 0.39 ms (−25 %) |
+
+The saving is the server's parse/analyze and the protocol Parse/Describe round on every repeat, not the plan — which is why nearly all of it survives `force_custom_plan`, the setting that removes the classic downside of prepared statements (a generic plan after ~5 executions picking worse indexes for range, `LIKE` or skewed filters).
+
+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.
 
 ## Runtime support
 
@@ -69,6 +85,8 @@ Transactions run on one checked-out client; nested `transaction()` calls become
 - `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.
 
+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".
+
 ## 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):

package/dist/index.d.ts

@@ -6,6 +6,7 @@
  * mapping. Only `VibeError` ever escapes.
  */
 import type { DatabaseAdapter } from "@vibeorm/runtime";
+import { type PlanCacheMode } from "./pool-config.ts";
 /** The single `pg` query form this adapter uses (config object, never overloads). */
 export type PgQueryConfig = {
     readonly text: string;
@@ -75,13 +76,36 @@ export type PgAdapterOptions = {
     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.
+     *
+     * Measured on this repo's benchmark (postgres 16, interleaved rounds):
+     * −17…−25 % on reads, −6 % on a by-key update — the server skips the
+     * parse/analyze and the protocol Parse/Describe round on every repeat. The
+     * gain survives {@link PgAdapterOptions.planCacheMode} `force_custom_plan`,
+     * which removes the classic downside (a generic plan after ~5 executions
+     * 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.
      */
     readonly preparedStatements?: boolean;
     /** Maximum entries in the prepared-statement name cache (default 1000, LRU). */
     readonly stmtCacheMax?: number;
+    /**
+     * PostgreSQL `plan_cache_mode` for every connection of the pool this adapter
+     * builds (default `"auto"`, the server default — nothing is sent). Pair
+     * `"force_custom_plan"` with {@link PgAdapterOptions.preparedStatements}: the
+     * statement is still prepared once, but planned with the real parameter
+     * values on every execution. Rides the `options` startup parameter, merged
+     * with whatever the connection string already carries (a URL that sets
+     * `plan_cache_mode` itself wins). Refused with `VIBE_CONFIG` together with
+     * a caller-supplied `pool` — the adapter never reconfigures a pool it does
+     * not own; set it on that pool's own `options` instead.
+     */
+    readonly planCacheMode?: PlanCacheMode;
 };
 /**
  * Create a VibeORM adapter backed by node-postgres.
@@ -103,12 +127,14 @@ export type PgAdapterOptions = {
 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 { createSavepointCounter, nextSavepointName } from "@vibeorm/runtime/adapter-kit";
+export type { SavepointCounter } from "@vibeorm/runtime/adapter-kit";
 export { createStatementNameCache } from "./statement-cache.ts";
 export type { StatementNameCache } from "./statement-cache.ts";
+export { buildPoolConfig, placePlanCacheMode } from "./pool-config.ts";
+export type { PlanCacheMode, StartupOptionsPlacement } from "./pool-config.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";
+export { DEFAULT_DEADLINE_CLOCK, engineStatementBudgetMs, isTransactionDeadlineError, startTransactionBudget, transactionClosedError, transactionDeadlineError, transactionOutcomeUnknownError, validateTransactionDeadline, } from "@vibeorm/runtime/adapter-kit";
+export type { BudgetStage, DeadlineClock, TransactionBudget, TransactionOutcome } from "@vibeorm/runtime/adapter-kit";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1,5 +1,17 @@
 // @bun
 // packages/adapter-pg/src/index.ts
+import {
+  createSavepointScope,
+  engineStatementBudgetMs,
+  isTransactionDeadlineError,
+  runNestedSavepoint,
+  runRootScope,
+  scopeTurn,
+  startTransactionBudget,
+  transactionOutcomeUnknownError,
+  validateTransactionDeadline
+} from "@vibeorm/runtime/adapter-kit";
+import { VibeError as VibeError4 } from "@vibeorm/schema";
 import pg from "pg";
 
 // packages/adapter-pg/src/errors.ts
@@ -70,142 +82,98 @@ class PgArrayParam {
     this.values = values;
   }
 }
+function serializeDate(params) {
+  const { value } = params;
+  const time = value.getTime();
+  if (Number.isNaN(time))
+    return value;
+  const year = value.getUTCFullYear();
+  if (year < 1 || year > 9999)
+    return value;
+  return value.toISOString();
+}
 function isDriverNativeValue(value) {
-  return value === null || value === undefined || typeof value !== "object" || value instanceof Date || ArrayBuffer.isView(value) || value instanceof ArrayBuffer;
+  return value === null || value === undefined || typeof value !== "object" || ArrayBuffer.isView(value) || value instanceof ArrayBuffer;
 }
 function serializeParams(params) {
   return params.values.map((value) => {
     if (value instanceof PgArrayParam)
-      return value.values;
+      return serializeList({ values: value.values });
+    if (value instanceof Date)
+      return serializeDate({ value });
     if (isDriverNativeValue(value))
       return value;
     return JSON.stringify(value);
   });
 }
+function serializeList(params) {
+  const { values } = params;
+  return values.some((value) => value instanceof Date) ? values.map((value) => value instanceof Date ? serializeDate({ value }) : value) : values;
+}
 function serializeParamsRaw(params) {
   return params.values.map((value) => {
     if (value instanceof PgArrayParam)
-      return value.values;
+      return serializeList({ values: value.values });
     if (Array.isArray(value))
-      return value;
+      return serializeList({ values: value });
+    if (value instanceof Date)
+      return serializeDate({ value });
     if (isDriverNativeValue(value))
       return value;
     return JSON.stringify(value);
   });
 }
 
-// packages/adapter-pg/src/savepoint-gate.ts
-import { AsyncLocalStorage } from "async_hooks";
-
-// packages/adapter-pg/src/savepoints.ts
-function createSavepointCounter() {
-  return { n: 0 };
-}
-function nextSavepointName(params) {
-  return `vibeorm_sp_${params.counter.n++}`;
-}
-
-// packages/adapter-pg/src/savepoint-gate.ts
-var CURRENT = new AsyncLocalStorage;
-function createSavepointScope() {
-  return { depth: 0, state: { counter: createSavepointCounter(), open: null } };
-}
-function runRootScope(params) {
-  return CURRENT.run(params.scope, params.body);
-}
-function scopeTurn(params) {
-  const open = params.scope.state.open;
-  if (mayProceed({ scope: params.scope, open }))
-    return;
-  return waitForTurn({ scope: params.scope });
+// packages/adapter-pg/src/pool-config.ts
+import { VibeError as VibeError2 } from "@vibeorm/schema";
+var PLAN_CACHE_MODES = ["auto", "force_custom_plan", "force_generic_plan"];
+function isPlanCacheMode(value) {
+  return typeof value === "string" && PLAN_CACHE_MODES.includes(value);
+}
+function assertPlanCacheMode(params) {
+  const { value } = params;
+  if (isPlanCacheMode(value))
+    return value;
+  throw new VibeError2({
+    code: "VIBE_CONFIG",
+    message: `planCacheMode must be one of ${PLAN_CACHE_MODES.map((mode) => `"${mode}"`).join(", ")}, received ${JSON.stringify(value)}`,
+    meta: { planCacheMode: value, allowed: PLAN_CACHE_MODES }
+  });
 }
-async function runNestedSavepoint(params) {
-  const { scope, execute, body } = params;
-  const node = await acquire({ scope });
-  try {
-    if (execute !== undefined)
-      await execute(`SAVEPOINT ${node.name}`);
-    let result;
-    try {
-      result = await CURRENT.run(node.scope, () => body(node.scope));
-    } catch (error) {
-      await drainDescendants({ node });
-      if (execute !== undefined) {
-        try {
-          await execute(`ROLLBACK TO SAVEPOINT ${node.name}`);
-        } catch {}
-      }
-      throw error;
-    }
-    await drainDescendants({ node });
-    if (execute !== undefined)
-      await execute(`RELEASE SAVEPOINT ${node.name}`);
-    return result;
-  } finally {
-    closeNode({ node });
+function placePlanCacheMode(params) {
+  const { connectionString, planCacheMode } = params;
+  if (planCacheMode === "auto")
+    return { connectionString, options: undefined };
+  const setting = `-c plan_cache_mode=${planCacheMode}`;
+  if (connectionString === undefined || !URL.canParse(connectionString)) {
+    return { connectionString, options: setting };
   }
-}
-function mayProceed(params) {
-  const { scope, open } = params;
-  if (open === null)
-    return true;
-  if (open.scope === scope)
-    return true;
-  if (open.scope.depth < scope.depth)
-    return true;
-  return CURRENT.getStore() === open.scope;
-}
-async function waitForTurn(params) {
-  for (;; ) {
-    const open = params.scope.state.open;
-    if (open === null || mayProceed({ scope: params.scope, open }))
-      return;
-    await open.settled;
+  const url = new URL(connectionString);
+  const existing = url.searchParams.get("options");
+  if (existing === null) {
+    return { connectionString, options: setting };
   }
-}
-async function acquire(params) {
-  const { scope } = params;
-  for (;; ) {
-    const open = scope.state.open;
-    if (mayProceed({ scope, open }))
-      return pushNode({ scope, parent: open });
-    await open.settled;
+  if (/(^|\s)-c\s*plan_cache_mode=/.test(existing)) {
+    return { connectionString, options: undefined };
   }
-}
-function pushNode(params) {
-  const { scope, parent } = params;
-  const state = scope.state;
-  let settle = () => {
-    return;
-  };
-  const settled = new Promise((resolve) => {
-    settle = () => resolve();
+  const merged = existing.trim().length === 0 ? setting : `${existing.trim()} ${setting}`;
+  url.searchParams.set("options", merged);
+  return { connectionString: url.toString(), options: merged };
+}
+function buildPoolConfig(params) {
+  const { max, statementTimeout, connectionTimeout } = params;
+  const placement = placePlanCacheMode({
+    connectionString: params.connectionString,
+    planCacheMode: params.planCacheMode ?? "auto"
   });
-  const node = {
-    scope: { depth: (parent === null ? 0 : parent.scope.depth) + 1, state },
-    name: nextSavepointName({ counter: state.counter }),
-    parent,
-    settled,
-    settle
-  };
-  state.open = node;
-  return node;
-}
-function closeNode(params) {
-  const { node } = params;
-  const state = node.scope.state;
-  if (state.open === node)
-    state.open = node.parent;
-  node.settle();
-}
-async function drainDescendants(params) {
-  const state = params.node.scope.state;
-  for (;; ) {
-    const open = state.open;
-    if (open === null || open === params.node || open.scope.depth <= params.node.scope.depth)
-      return;
-    await open.settled;
-  }
+  const config = { connectionString: placement.connectionString, max };
+  if (statementTimeout !== undefined)
+    config.statement_timeout = statementTimeout;
+  if (connectionTimeout !== undefined)
+    config.connectionTimeoutMillis = connectionTimeout;
+  if (placement.options !== undefined)
+    config.options = placement.options;
+  return config;
 }
 
 // packages/adapter-pg/src/statement-cache.ts
@@ -231,125 +199,6 @@ function createStatementNameCache(params) {
   };
 }
 
-// packages/adapter-pg/src/transaction-budget.ts
-import { VibeError as VibeError2 } from "@vibeorm/schema";
-var DEFAULT_DEADLINE_CLOCK = () => Date.now();
-function validateTransactionDeadline(params) {
-  const { options, support, provider } = params;
-  const deadline = options?.deadline;
-  if (deadline === undefined)
-    return;
-  if (support === "unsupported") {
-    throw new VibeError2({
-      code: "VIBE_UNSUPPORTED_CAPABILITY",
-      message: `${provider} cannot enforce a transaction deadline \u2014 remove the \`deadline\` option`,
-      meta: { provider, feature: "transactionDeadline", supported: support }
-    });
-  }
-  if (!Number.isInteger(deadline.totalMs) || deadline.totalMs <= 0) {
-    throw new VibeError2({
-      code: "VIBE_VALIDATION",
-      message: `transaction deadline \`totalMs\` must be a positive integer of milliseconds, received ${String(deadline.totalMs)}`,
-      meta: { provider, feature: "transactionDeadline", totalMs: deadline.totalMs }
-    });
-  }
-  const requested = deadline.enforcement ?? "between-statements";
-  if (requested === "cancel-running-statements" && support !== "cancel-running-statements") {
-    throw new VibeError2({
-      code: "VIBE_UNSUPPORTED_CAPABILITY",
-      message: `${provider} cannot cancel a statement that is already running, so the requested ` + "`cancel-running-statements` deadline guarantee is refused rather than silently downgraded \u2014 " + 'ask for "between-statements" if a budget checked between statements is enough',
-      meta: { provider, feature: "transactionDeadline", requested, supported: support }
-    });
-  }
-}
-function startTransactionBudget(params) {
-  const { options, provider } = params;
-  const clock = params.clock ?? DEFAULT_DEADLINE_CLOCK;
-  const deadline = options?.deadline;
-  const totalMs = deadline === undefined ? null : deadline.totalMs;
-  const enforcement = deadline === undefined ? null : deadline.enforcement ?? "between-statements";
-  const expiresAt = totalMs === null ? null : clock() + totalMs;
-  let outcome = null;
-  const budget = {
-    enforcement,
-    totalMs,
-    statementTimeoutMs: options?.timeout ?? null,
-    remainingMs() {
-      return expiresAt === null ? null : Math.max(0, expiresAt - clock());
-    },
-    expired() {
-      return expiresAt !== null && clock() >= expiresAt;
-    },
-    assertUsable(assertParams) {
-      if (outcome !== null) {
-        throw transactionClosedError({ provider, outcome, stage: assertParams.stage });
-      }
-      if (expiresAt !== null && clock() >= expiresAt) {
-        throw transactionDeadlineError({
-          provider,
-          stage: assertParams.stage,
-          totalMs,
-          overdueMs: clock() - expiresAt
-        });
-      }
-    },
-    close(closeParams) {
-      if (outcome === null)
-        outcome = closeParams.outcome;
-    },
-    get outcome() {
-      return outcome;
-    }
-  };
-  return budget;
-}
-function engineStatementBudgetMs(params) {
-  const { budget } = params;
-  if (budget.enforcement !== "cancel-running-statements")
-    return null;
-  const remaining = budget.remainingMs();
-  if (remaining === null)
-    return null;
-  const totalBound = Math.max(1, Math.ceil(remaining));
-  return budget.statementTimeoutMs !== null && budget.statementTimeoutMs > 0 ? Math.min(totalBound, budget.statementTimeoutMs) : totalBound;
-}
-function transactionDeadlineError(params) {
-  const { provider, stage, totalMs, overdueMs } = params;
-  const what = stage === "commit" ? "the transaction was rolled back instead of committed" : "the statement was never sent and the transaction is being rolled back";
-  return new VibeError2({
-    code: "VIBE_TRANSACTION",
-    message: `transaction deadline of ${totalMs} ms expired ${Math.max(0, Math.round(overdueMs))} ms ago \u2014 ${what}. ` + "Nothing is retried automatically: work the callback did outside the database may already have happened.",
-    meta: { provider, reason: "transaction-deadline", stage, totalMs, overdueMs: Math.max(0, Math.round(overdueMs)) }
-  });
-}
-function transactionClosedError(params) {
-  const { provider, outcome, stage } = params;
-  return new VibeError2({
-    code: "VIBE_TRANSACTION",
-    message: `this transaction has already finished (${outcome}), so its client can no longer be used \u2014 ` + "a handle kept past the end of `$transaction` would run outside the transaction, on a connection " + "that now belongs to someone else",
-    meta: { provider, reason: "transaction-closed", outcome, stage }
-  });
-}
-function transactionOutcomeUnknownError(params) {
-  const { provider, totalMs, cause } = params;
-  return new VibeError2({
-    code: "VIBE_TRANSACTION",
-    message: `transaction deadline of ${totalMs} ms expired and the rollback that should have cleaned up failed \u2014 ` + "the commit state of this transaction is UNKNOWN. It is not retried automatically; inspect the data " + "before deciding.",
-    meta: {
-      provider,
-      reason: "transaction-outcome-unknown",
-      outcome: "unknown",
-      totalMs,
-      rollbackFailed: true
-    },
-    cause
-  });
-}
-function isTransactionDeadlineError(error) {
-  const reason = error?.meta?.reason;
-  return reason === "transaction-deadline";
-}
-
 // packages/adapter-pg/src/transaction-sql.ts
 import { VibeError as VibeError3 } from "@vibeorm/schema";
 var ISOLATION_LEVEL_SQL = Object.freeze({
@@ -409,6 +258,17 @@ function refuseNestedTransactionOptions(params) {
 }
 
 // packages/adapter-pg/src/index.ts
+import { createSavepointCounter, nextSavepointName } from "@vibeorm/runtime/adapter-kit";
+import {
+  DEFAULT_DEADLINE_CLOCK,
+  engineStatementBudgetMs as engineStatementBudgetMs2,
+  isTransactionDeadlineError as isTransactionDeadlineError2,
+  startTransactionBudget as startTransactionBudget2,
+  transactionClosedError,
+  transactionDeadlineError,
+  transactionOutcomeUnknownError as transactionOutcomeUnknownError2,
+  validateTransactionDeadline as validateTransactionDeadline2
+} from "@vibeorm/runtime/adapter-kit";
 var POOL_STATEMENT_NAMES = new WeakMap;
 function guardBackgroundErrors(params) {
   const { client } = params;
@@ -432,18 +292,55 @@ var BUDGETS = Object.freeze({
 });
 var NUMERIC_ARRAY_OID = 1231;
 var TEXT_ARRAY_OID = 1009;
+var TIMESTAMP_OID = 1114;
+var TIMESTAMP_ARRAY_OID = 1115;
+var DATE_OID = 1082;
+var DATE_ARRAY_OID = 1182;
+var driverTypeParser = pg.types.getTypeParser;
+var ZONE_LESS_TEXT = /^\d{4}-\d{2}-\d{2}(?: \d{2}:\d{2}:\d{2}(?:\.\d{1,6})?)?$/;
+function parseZoneLessAsUtc(value) {
+  if (ZONE_LESS_TEXT.test(value)) {
+    const iso = value.includes(" ") ? `${value.replace(" ", "T").replace(/(\.\d{3})\d+$/, "$1")}Z` : value;
+    const parsed = new Date(iso);
+    if (!Number.isNaN(parsed.getTime()))
+      return parsed;
+  }
+  return driverTypeParser(TIMESTAMP_OID, "text")(value);
+}
+function parseZoneLessArrayAsUtc(value) {
+  const mapElements = (element) => {
+    if (element === null)
+      return null;
+    if (Array.isArray(element))
+      return element.map(mapElements);
+    return parseZoneLessAsUtc(String(element));
+  };
+  return mapElements(driverTypeParser(TEXT_ARRAY_OID, "text")(value));
+}
 var EXACT_TYPES = {
   getTypeParser(oid, format) {
-    if (oid === NUMERIC_ARRAY_OID && (format === undefined || format === "text")) {
-      return driverTypeParser(TEXT_ARRAY_OID, "text");
+    if (format === undefined || format === "text") {
+      if (oid === NUMERIC_ARRAY_OID)
+        return driverTypeParser(TEXT_ARRAY_OID, "text");
+      if (oid === TIMESTAMP_OID || oid === DATE_OID)
+        return parseZoneLessAsUtc;
+      if (oid === TIMESTAMP_ARRAY_OID || oid === DATE_ARRAY_OID)
+        return parseZoneLessArrayAsUtc;
     }
     return driverTypeParser(oid, format);
   }
 };
-var driverTypeParser = pg.types.getTypeParser;
 function pgAdapter(options) {
   const usePrepared = options?.preparedStatements ?? false;
   const stmtCacheMax = options?.stmtCacheMax ?? 1000;
+  const planCacheMode = options?.planCacheMode === undefined ? "auto" : assertPlanCacheMode({ value: options.planCacheMode });
+  if (planCacheMode !== "auto" && options?.pool !== undefined) {
+    throw new VibeError4({
+      code: "VIBE_CONFIG",
+      message: "planCacheMode configures the pool the adapter builds \u2014 it cannot be applied to a caller-supplied `pool`; " + 'set `options: "-c plan_cache_mode=\u2026"` on that pool instead',
+      meta: { planCacheMode }
+    });
+  }
   let pool = null;
   let ownsPool = false;
   let rawSession = null;
@@ -456,16 +353,13 @@ function pgAdapter(options) {
       ownsPool = false;
       return pool;
     }
-    const config = {
+    const config = buildPoolConfig({
       connectionString: options?.connectionString ?? process.env.DATABASE_URL,
-      max: options?.max ?? 10
-    };
-    if (options?.statementTimeout !== undefined) {
-      config.statement_timeout = options.statementTimeout;
-    }
-    if (options?.connectionTimeout !== undefined) {
-      config.connectionTimeoutMillis = options.connectionTimeout;
-    }
+      max: options?.max ?? 10,
+      ...options?.statementTimeout === undefined ? {} : { statementTimeout: options.statementTimeout },
+      ...options?.connectionTimeout === undefined ? {} : { connectionTimeout: options.connectionTimeout },
+      planCacheMode
+    });
     const PoolCtor = pg.Pool;
     pool = new PoolCtor(config);
     pool.on?.("error", () => {});
@@ -657,24 +551,26 @@ function pgAdapter(options) {
   };
 }
 export {
-  validateTransactionDeadline,
-  transactionOutcomeUnknownError,
+  validateTransactionDeadline2 as validateTransactionDeadline,
+  transactionOutcomeUnknownError2 as transactionOutcomeUnknownError,
   transactionDeadlineError,
   transactionClosedError,
   statementTimeoutStatement,
-  startTransactionBudget,
+  startTransactionBudget2 as startTransactionBudget,
   serializeParamsRaw,
   serializeParams,
   refuseNestedTransactionOptions,
+  placePlanCacheMode,
   pgErrorSqlstate,
   pgAdapter,
   nextSavepointName,
   mapPgDriverError,
-  isTransactionDeadlineError,
-  engineStatementBudgetMs,
+  isTransactionDeadlineError2 as isTransactionDeadlineError,
+  engineStatementBudgetMs2 as engineStatementBudgetMs,
   createStatementNameCache,
   createSavepointCounter,
   classifyRawTransactionControl,
+  buildPoolConfig,
   beginStatement,
   PgArrayParam,
   PG_SQLSTATE_REASONS,
@@ -683,4 +579,4 @@ export {
   DEFAULT_DEADLINE_CLOCK
 };
 
-//# debugId=17E44C1AF7E3C0D164756E2164756E21
+//# debugId=79BF9E77B467A34F64756E2164756E21