@vibeorm/adapter-pg 5.0.1 → 5.1.0

package/dist/index.js

@@ -29,13 +29,37 @@ import {
   startTransactionBudget,
   transactionAbortedError as transactionAbortedError2,
   validateTransactionDeadline,
-  parseExtendedDateTimeText
+  parseExtendedDateTimeText,
+  assertStatementName
 } from "@vibeorm/runtime/adapter-kit";
-import { VibeError as VibeError7 } from "@vibeorm/schema";
+import { VibeError as VibeError9 } from "@vibeorm/schema";
 import pg3 from "pg";
 
 // packages/adapter-pg/src/batch.ts
+import { VibeError } from "@vibeorm/schema";
 import pg from "pg";
+function statementBookOf(params) {
+  const connection = params.connection;
+  if (connection === null || typeof connection !== "object")
+    return;
+  const { parsedStatements, submittedNamedStatements, on, removeListener } = connection;
+  if (typeof parsedStatements !== "object" || parsedStatements === null)
+    return;
+  if (typeof submittedNamedStatements !== "object" || submittedNamedStatements === null)
+    return;
+  if (typeof on !== "function" || typeof removeListener !== "function")
+    return;
+  return {
+    parsed: parsedStatements,
+    submitted: submittedNamedStatements,
+    onParseComplete: (listener) => {
+      on.call(connection, "parseComplete", listener);
+      return () => {
+        removeListener.call(connection, "parseComplete", listener);
+      };
+    }
+  };
+}
 var prepareValue = (() => {
   const utils = pg.utils;
   return typeof utils?.prepareValue === "function" ? utils.prepareValue : undefined;
@@ -78,6 +102,11 @@ class PgBatch {
   resolve = () => {
     return;
   };
+  book = undefined;
+  parses = [];
+  parsesAnswered = 0;
+  stopParseTracking = undefined;
+  written = false;
   constructor(params) {
     this.steps = params.steps;
     this.types = params.types;
@@ -87,18 +116,85 @@ class PgBatch {
   }
   submit(connection) {
     const writer = connection;
+    if (writer.stream?.writable === false) {
+      return new VibeError({
+        code: "VIBE_ADAPTER",
+        message: "the connection's socket is no longer writable: the batch was not sent",
+        meta: { adapter: "pg", reason: "connection-not-writable" }
+      });
+    }
+    const book = this.steps.some((step) => step.name !== undefined) ? statementBookOf({ connection }) : undefined;
+    const pending = new Map;
+    const names = [];
+    for (const step of this.steps) {
+      const name = step.name;
+      if (name === undefined || book === undefined) {
+        names.push({ parse: true });
+        continue;
+      }
+      const known = book.parsed[name] ?? book.submitted[name] ?? pending.get(name);
+      if (known !== undefined && known !== step.text) {
+        return new VibeError({
+          code: "VIBE_VALIDATION",
+          message: `statement name "${name}" already names another SQL text on this connection: one name means one text`,
+          meta: { adapter: "pg", reason: "statement-name-reused", name }
+        });
+      }
+      if (known === undefined)
+        pending.set(name, step.text);
+      names.push({ parse: known === undefined, name });
+    }
+    if (book !== undefined)
+      for (const [name, text] of pending)
+        book.submitted[name] = text;
+    this.written = true;
+    if (names.some((entry) => entry.parse && entry.name !== undefined) && book !== undefined) {
+      this.book = book;
+      this.stopParseTracking = book.onParseComplete(() => {
+        this.answerParse();
+      });
+    }
     writer.stream?.cork?.();
     try {
-      for (const step of this.steps) {
-        writer.parse({ text: step.text, types: [] });
-        writer.bind({ values: step.values ?? [] });
+      this.steps.forEach((step, index) => {
+        const entry = names[index];
+        if (entry.parse) {
+          writer.parse(entry.name === undefined ? { text: step.text, types: [] } : { text: step.text, name: entry.name, types: [] });
+          this.parses.push(entry.name === undefined ? null : { name: entry.name, text: step.text });
+        }
+        writer.bind(entry.name === undefined ? { values: step.values ?? [] } : { statement: entry.name, values: step.values ?? [] });
         writer.describe({ type: "P", name: "" });
         writer.execute({ portal: "", rows: 0 });
-      }
+      });
       writer.sync();
     } finally {
       writer.stream?.uncork?.();
     }
+    return null;
+  }
+  answerParse() {
+    const book = this.book;
+    if (book === undefined || this.parsesAnswered >= this.parses.length)
+      return;
+    const parse = this.parses[this.parsesAnswered];
+    this.parsesAnswered += 1;
+    if (parse === null || parse === undefined)
+      return;
+    book.parsed[parse.name] = parse.text;
+    delete book.submitted[parse.name];
+  }
+  endParseTracking() {
+    const book = this.book;
+    if (book === undefined)
+      return;
+    for (const parse of this.parses.slice(this.parsesAnswered)) {
+      if (parse !== null && book.submitted[parse.name] === parse.text)
+        delete book.submitted[parse.name];
+    }
+    this.parsesAnswered = this.parses.length;
+    this.book = undefined;
+    this.stopParseTracking?.();
+    this.stopParseTracking = undefined;
   }
   handleRowDescription(message) {
     this.rows = [];
@@ -152,6 +248,8 @@ class PgBatch {
     this.outcomes.push({ status: "ok", result: { rows: [], rowCount: null } });
   }
   handleError(error) {
+    if (isServerError(error))
+      this.endParseTracking();
     if (this.settled)
       return;
     if (!isServerError(error)) {
@@ -164,6 +262,7 @@ class PgBatch {
     this.finish({});
   }
   handleReadyForQuery() {
+    this.endParseTracking();
     this.finish({});
   }
   handlePortalSuspended() {}
@@ -178,7 +277,7 @@ class PgBatch {
     this.callback?.(params.transportError ?? null);
     this.resolve({
       steps: this.outcomes,
-      ...params.transportError === undefined ? {} : { transportError: params.transportError }
+      ...params.transportError === undefined ? {} : { transportError: params.transportError, ...this.written ? {} : { unsent: true } }
     });
   }
 }
@@ -198,10 +297,10 @@ function firstBatchFailure(params) {
 }
 
 // packages/adapter-pg/src/connection-group.ts
-import { VibeError } from "@vibeorm/schema";
+import { VibeError as VibeError2 } from "@vibeorm/schema";
 import { transactionAbortedError } from "@vibeorm/runtime/adapter-kit";
 function connectionGroupMisuse(params) {
-  return new VibeError({ code: "VIBE_INTERNAL", message: `pipeline lane group: ${params.message}`, meta: { reason: "pipeline-lane-group" } });
+  return new VibeError2({ code: "VIBE_INTERNAL", message: `pipeline lane group: ${params.message}`, meta: { reason: "pipeline-lane-group" } });
 }
 function openConnectionGroup(params) {
   const { driver } = params;
@@ -309,7 +408,7 @@ function openConnectionGroup(params) {
 }
 
 // packages/adapter-pg/src/connection-string.ts
-import { VibeError as VibeError2 } from "@vibeorm/schema";
+import { VibeError as VibeError3 } from "@vibeorm/schema";
 function lastValue(params) {
   const values = params.search.getAll(params.key);
   return values.length === 0 ? undefined : values[values.length - 1];
@@ -328,7 +427,7 @@ function honourSystemRootCert(params) {
   const ssl = lastValue({ search, key: "ssl" });
   const weaker = sslmode !== undefined && sslmode !== "verify-full" ? { parameter: "sslmode", value: sslmode } : ssl !== undefined && ssl !== "true" && ssl !== "1" ? { parameter: "ssl", value: ssl } : undefined;
   if (weaker !== undefined) {
-    throw new VibeError2({
+    throw new VibeError3({
       code: "VIBE_CONFIG",
       message: `pgAdapter \`${option}\` combines sslrootcert=system with ${weaker.parameter}=${JSON.stringify(weaker.value)}. ` + "libpq allows sslrootcert=system only with sslmode=verify-full (its default when sslmode is omitted): any certificate " + "the system trusts would otherwise vouch for a server that is not yours. Use sslmode=verify-full, or remove the setting.",
       meta: { adapter: "pg", reason: "sslrootcert-system-weak-sslmode", option, parameter: weaker.parameter, value: weaker.value }
@@ -370,7 +469,7 @@ function createClientTurns() {
 
 // packages/adapter-pg/src/read-cancellation.ts
 import pg2 from "pg";
-import { VibeError as VibeError4 } from "@vibeorm/schema";
+import { VibeError as VibeError5 } from "@vibeorm/schema";
 import { assertReadExecution, readCancelledError } from "@vibeorm/runtime/adapter-kit";
 
 // packages/adapter-pg/src/config.ts
@@ -379,7 +478,7 @@ var PG_READ_CANCELLATION = Object.freeze({
 });
 
 // packages/adapter-pg/src/errors.ts
-import { VibeError as VibeError3 } from "@vibeorm/schema";
+import { VibeError as VibeError4 } from "@vibeorm/schema";
 var PG_SQLSTATE_ERROR_CODES = Object.freeze({
   "23P01": "VIBE_EXCLUSION_VIOLATION",
   "23505": "VIBE_UNIQUE_VIOLATION",
@@ -407,7 +506,7 @@ var PG_SQLSTATE_REASONS = Object.freeze({
   "40001": "serialization-failure",
   "25006": "read-only-transaction"
 });
-var NAMED_STATEMENT_POOLER_HINT = "Hint: with preparedStatements: true every query must reach the backend that prepared its name. " + "Use a direct connection, session pooling, or PgBouncer 1.21+ with max_prepared_statements > 0; " + "behind a transaction-mode pooler without prepared-statement support, turn preparedStatements off.";
+var NAMED_STATEMENT_POOLER_HINT = "Hint: with preparedStatements: true or a named raw statement, every query must reach the backend that prepared its name. " + "Use a direct connection, session pooling, or PgBouncer 1.21+ with max_prepared_statements > 0; " + "behind a transaction-mode pooler without prepared-statement support, turn preparedStatements off and send raw statements without a name.";
 var PG_SQLSTATE_HINTS = Object.freeze({
   "26000": NAMED_STATEMENT_POOLER_HINT,
   "42P05": NAMED_STATEMENT_POOLER_HINT
@@ -426,7 +525,7 @@ function pgErrorSqlstate(params) {
 }
 function mapPgDriverError(params) {
   const { error } = params;
-  if (error instanceof VibeError3)
+  if (error instanceof VibeError4)
     return error;
   const source = error !== null && typeof error === "object" ? error : {};
   const sqlstate = pgErrorSqlstate({ error });
@@ -449,7 +548,7 @@ function mapPgDriverError(params) {
   const driverMessage = readStringField({ source, key: "message" }) ?? (typeof error === "string" ? error : "unknown postgres driver error");
   const hint = sqlstate === undefined ? undefined : PG_SQLSTATE_HINTS[sqlstate];
   const message = hint === undefined ? driverMessage : `${driverMessage}. ${hint}`;
-  return new VibeError3({ code, message, meta, cause: error });
+  return new VibeError4({ code, message, meta, cause: error });
 }
 async function runMapped(fn) {
   try {
@@ -472,14 +571,14 @@ function createPgReadCancellation(params) {
       if (query.execution?.cancellation !== "running")
         return query.send();
       if (params.target.pipeline === true || (params.target.connectionParameters?.query_timeout ?? 0) > 0) {
-        throw new VibeError4({ code: "VIBE_UNSUPPORTED_CAPABILITY", message: "Running cancellation requires a non-pipelined target without local query_timeout", meta: { capability: "readCancellation", reason: "target-lifetime" } });
+        throw new VibeError5({ code: "VIBE_UNSUPPORTED_CAPABILITY", message: "Running cancellation requires a non-pipelined target without local query_timeout", meta: { capability: "readCancellation", reason: "target-lifetime" } });
       }
       const address = params.connectionString;
       if (address === undefined)
-        throw new VibeError4({ code: "VIBE_INTERNAL", message: "Running cancellation requires a control address" });
+        throw new VibeError5({ code: "VIBE_INTERNAL", message: "Running cancellation requires a control address" });
       const token = `vibe_cancel_${crypto.randomUUID()}`;
       if (!URL.canParse(address))
-        throw new VibeError4({ code: "VIBE_CONFIG", message: "The PostgreSQL cancellation control address must be a URL" });
+        throw new VibeError5({ code: "VIBE_CONFIG", message: "The PostgreSQL cancellation control address must be a URL" });
       const url = new URL(address);
       url.searchParams.delete("query_timeout");
       url.searchParams.set("connect_timeout", String(PG_READ_CANCELLATION.controlTimeoutMs / 1000));
@@ -526,7 +625,7 @@ function createPgReadCancellation(params) {
         if (preflightAborted)
           throw readCancelledError({ stage: "waiting-for-connection" });
         if (witness === undefined || typeof witness.pid !== "number" || typeof witness.backend_start !== "string" || typeof witness.datname !== "string" || typeof witness.usename !== "string" || witness.tag !== token) {
-          throw new VibeError4({ code: "VIBE_UNSUPPORTED_CAPABILITY", message: "Cannot prove the exact PostgreSQL cancellation target", meta: { capability: "readCancellation", reason: "target-witness" } });
+          throw new VibeError5({ code: "VIBE_UNSUPPORTED_CAPABILITY", message: "Cannot prove the exact PostgreSQL cancellation target", meta: { capability: "readCancellation", reason: "target-witness" } });
         }
         assertReadExecution({ execution: query.execution, effect: "read", support, provider: "postgresql", stage: "waiting-for-connection" });
         listener = () => {
@@ -543,7 +642,7 @@ function createPgReadCancellation(params) {
             throw error;
           };
           settlementTimer = setTimeout(() => {
-            controlFailure = new VibeError4({ code: "VIBE_ADAPTER", message: "PostgreSQL read did not settle after cancellation; its exact session was discarded", meta: { reason: "read-cancellation-unsettled", databaseCancelled: false } });
+            controlFailure = new VibeError5({ code: "VIBE_ADAPTER", message: "PostgreSQL read did not settle after cancellation; its exact session was discarded", meta: { reason: "read-cancellation-unsettled", databaseCancelled: false } });
             if (!terminated) {
               terminated = true;
               params.terminate();
@@ -555,7 +654,7 @@ function createPgReadCancellation(params) {
           })).then((result) => {
             signalSent = rowsOf(result)[0]?.signalled === true;
             if (!signalSent)
-              failControl(new VibeError4({ code: "VIBE_UNSUPPORTED_CAPABILITY", message: "The control endpoint did not signal the exact PostgreSQL target", meta: { capability: "readCancellation", reason: "target-not-signalled", databaseCancelled: false } }));
+              failControl(new VibeError5({ code: "VIBE_UNSUPPORTED_CAPABILITY", message: "The control endpoint did not signal the exact PostgreSQL target", meta: { capability: "readCancellation", reason: "target-not-signalled", databaseCancelled: false } }));
           }, failControl);
           cancel.then(() => {
             return;
@@ -586,12 +685,12 @@ function createPgReadCancellation(params) {
             }, () => {
               return;
             });
-          const sqlstate = error instanceof VibeError4 ? error.meta.sqlstate : pgErrorSqlstate({ error });
+          const sqlstate = error instanceof VibeError5 ? error.meta.sqlstate : pgErrorSqlstate({ error });
           if (terminated && controlFailure !== undefined && sqlstate === undefined)
             throw controlFailure;
           if (attempted && signalSent && sqlstate === "57014") {
             const cancelled = readCancelledError({ stage: "running", databaseCancelled: true, cause: error });
-            throw new VibeError4({ code: cancelled.code, message: cancelled.message, meta: { ...cancelled.meta, sqlstate: "57014" }, cause: error });
+            throw new VibeError5({ code: cancelled.code, message: cancelled.message, meta: { ...cancelled.meta, sqlstate: "57014" }, cause: error });
           }
           throw error;
         });
@@ -673,7 +772,7 @@ function serializeParamsRaw(params) {
 }
 
 // packages/adapter-pg/src/pool-config.ts
-import { VibeError as VibeError5 } from "@vibeorm/schema";
+import { VibeError as VibeError6 } 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);
@@ -682,7 +781,7 @@ function assertPlanCacheMode(params) {
   const { value } = params;
   if (isPlanCacheMode(value))
     return value;
-  throw new VibeError5({
+  throw new VibeError6({
     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 }
@@ -712,7 +811,7 @@ function assertIdleTimeout(params) {
   const { value } = params;
   if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 2147483647)
     return value;
-  throw new VibeError5({
+  throw new VibeError6({
     code: "VIBE_CONFIG",
     message: "pgAdapter `idleTimeout` must be integer milliseconds from 0 through 2,147,483,647 (0 keeps idle connections open).",
     meta: { adapter: "pg", reason: "invalid-idle-timeout", option: "idleTimeout" }
@@ -722,7 +821,7 @@ function assertPoolMin(params) {
   const { value, max } = params;
   if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= max)
     return value;
-  throw new VibeError5({
+  throw new VibeError6({
     code: "VIBE_CONFIG",
     message: `pgAdapter \`min\` must be an integer from 0 through \`max\` (${max}).`,
     meta: { adapter: "pg", reason: "invalid-pool-min", option: "min", max }
@@ -750,6 +849,7 @@ function buildPoolConfig(params) {
 
 // packages/adapter-pg/src/statement-cache.ts
 import { createHash } from "crypto";
+import { VibeError as VibeError7 } from "@vibeorm/schema";
 var DEFAULT_PROMOTE_AFTER = 2;
 var SIGHTINGS_PER_NAME = 4;
 var NAME_PREFIX = "vibeorm_";
@@ -811,6 +911,25 @@ function createStatementNameCache(params) {
     }
   };
 }
+function createRawStatementNames() {
+  const texts = new Map;
+  return {
+    admit(params) {
+      const known = texts.get(params.name);
+      if (known === undefined) {
+        texts.set(params.name, params.text);
+        return;
+      }
+      if (known === params.text)
+        return;
+      throw new VibeError7({
+        code: "VIBE_VALIDATION",
+        message: `statement name "${params.name}" already names another SQL text on this pool: one name means one text (give the new text its own name)`,
+        meta: { adapter: "pg", reason: "statement-name-reused", name: params.name }
+      });
+    }
+  };
+}
 
 // packages/adapter-pg/src/timestamp-text.ts
 var DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
@@ -893,7 +1012,7 @@ function parsePlainTimestampText(params) {
 }
 
 // packages/adapter-pg/src/transaction-sql.ts
-import { VibeError as VibeError6 } from "@vibeorm/schema";
+import { VibeError as VibeError8 } from "@vibeorm/schema";
 import { refuseNestedTransactionOptions } from "@vibeorm/runtime/adapter-kit";
 var ISOLATION_LEVEL_SQL = Object.freeze({
   ReadCommitted: "READ COMMITTED",
@@ -916,7 +1035,7 @@ function openTransactionStatement(params) {
 function statementTimeoutStatement(params) {
   const { timeout } = params;
   if (!Number.isInteger(timeout) || timeout < 0) {
-    throw new VibeError6({
+    throw new VibeError8({
       code: "VIBE_VALIDATION",
       message: `transaction timeout must be a non-negative integer of milliseconds, received ${String(timeout)}`,
       meta: { timeout }
@@ -953,32 +1072,32 @@ import {
   validateTransactionDeadline as validateTransactionDeadline2
 } from "@vibeorm/runtime/adapter-kit";
 function laneGroupMisuse(params) {
-  return new VibeError7({ code: "VIBE_INTERNAL", message: `pipeline lane group: ${params.message}`, meta: { reason: "pipeline-lane-group" } });
+  return new VibeError9({ code: "VIBE_INTERNAL", message: `pipeline lane group: ${params.message}`, meta: { reason: "pipeline-lane-group" } });
 }
 var MAX_STATEMENT_TIMEOUT_MS = 2147483647;
 var ignore = () => {
   return;
 };
 function predecessorClosedError() {
-  return new VibeError7({
+  return new VibeError9({
     code: "VIBE_TRANSACTION",
     message: "pipeline(): an earlier lane of this ordered scope closed without issuing its statement, so this statement was not sent " + "(the operation before it failed before it reached the database)",
     meta: { reason: "pipeline-predecessor-closed" }
   });
 }
 function orderedLaneMisuse(params) {
-  return new VibeError7({ code: "VIBE_INTERNAL", message: `pipeline(): ${params.message}`, meta: { reason: "pipeline-ordered-lane" } });
+  return new VibeError9({ code: "VIBE_INTERNAL", message: `pipeline(): ${params.message}`, meta: { reason: "pipeline-ordered-lane" } });
 }
 var COMMIT_STEP = Object.freeze({ text: "COMMIT" });
 function commitSentRefusal() {
-  return new VibeError7({
+  return new VibeError9({
     code: "VIBE_TRANSACTION",
     message: "this transaction already sent its COMMIT together with its last statement, so it accepts no further statement",
     meta: { provider: PROVIDER, reason: "commit-sent" }
   });
 }
 function finalStatementMisuse() {
-  return new VibeError7({
+  return new VibeError9({
     code: "VIBE_INTERNAL",
     message: "withCommit(): a view carries ONE statement, the transaction's last",
     meta: { reason: "with-commit-second-statement" }
@@ -993,15 +1112,16 @@ function finalResult(params) {
   return Array.isArray(params.result) ? params.result.at(-1) ?? { rows: [], rowCount: 0 } : params.result;
 }
 var POOL_STATEMENT_NAMES = new WeakMap;
+var POOL_RAW_STATEMENT_NAMES = new WeakMap;
 function isConnectionLoss(params) {
   const { error } = params;
-  if (!(error instanceof VibeError7))
+  if (!(error instanceof VibeError9))
     return true;
   const sqlstate = error.meta.sqlstate;
   return typeof sqlstate !== "string" || sqlstate.startsWith("08") || ["57P01", "57P02", "57P03"].includes(sqlstate);
 }
 function commitOutcomeUnknownError(params) {
-  return new VibeError7({
+  return new VibeError9({
     code: "VIBE_TRANSACTION",
     message: "the connection was lost while COMMIT was in flight, so the transaction's outcome is unknown: the write may have committed. The connection was discarded; inspect the data before retrying.",
     meta: { provider: PROVIDER, reason: "transaction-outcome-unknown", outcome: "unknown", stage: "commit" },
@@ -1010,6 +1130,10 @@ function commitOutcomeUnknownError(params) {
 }
 var NEVER_REUSE_SQLSTATE_CLASSES = new Set(["08", "53", "57", "58", "XX"]);
 var STALE_STATEMENT_SQLSTATES = new Set(["0A000", "26000", "42P05"]);
+function isStaleStatementFailure(params) {
+  const sqlstate = mapPgDriverError({ error: params.error }).meta.sqlstate;
+  return typeof sqlstate === "string" && STALE_STATEMENT_SQLSTATES.has(sqlstate);
+}
 function observeReadyForQuery(params) {
   const client = params.client;
   let backgroundFailure = false;
@@ -1030,7 +1154,7 @@ function observeReadyForQuery(params) {
   client.on("end", onEnd);
   return {
     reusableAfter: async ({ error, named }) => {
-      if (!(error instanceof VibeError7))
+      if (!(error instanceof VibeError9))
         return false;
       const sqlstate = error.meta.sqlstate;
       if (typeof sqlstate !== "string" || NEVER_REUSE_SQLSTATE_CLASSES.has(sqlstate.slice(0, 2)))
@@ -1160,7 +1284,7 @@ function takeAddress(params) {
   if (typeof connectionString === "string" && connectionString.trim() !== "") {
     return { connectionString: honourSystemRootCert({ connectionString, option: "connectionString" }) };
   }
-  throw new VibeError7({
+  throw new VibeError9({
     code: "VIBE_CONFIG",
     message: "pgAdapter needs an explicit address: pass `connectionString` (a PostgreSQL URL) or an existing `pool`. " + "The adapter does not read DATABASE_URL or the PG* environment variables.",
     meta: { adapter: "pg", reason: "missing-address" }
@@ -1194,7 +1318,7 @@ function pgAdapter(options) {
   const planCacheMode = options?.planCacheMode === undefined ? "auto" : assertPlanCacheMode({ value: options.planCacheMode });
   const idleTimeout = "pool" in address || options?.idleTimeout === undefined ? undefined : assertIdleTimeout({ value: options.idleTimeout });
   if (options?.min !== undefined && "pool" in address) {
-    throw new VibeError7({
+    throw new VibeError9({
       code: "VIBE_CONFIG",
       message: "pgAdapter `min` configures the pool the adapter builds \u2014 it cannot be applied to a caller-supplied `pool`; set `min` (and `idleTimeoutMillis`) on that pool instead",
       meta: { adapter: "pg", reason: "pool-min-with-injected-pool", option: "min" }
@@ -1202,7 +1326,7 @@ function pgAdapter(options) {
   }
   const poolMin = options?.min === undefined ? undefined : assertPoolMin({ value: options.min, max: options.max ?? 10 });
   if (planCacheMode !== "auto" && "pool" in address) {
-    throw new VibeError7({
+    throw new VibeError9({
       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 }
@@ -1244,6 +1368,14 @@ function pgAdapter(options) {
     POOL_STATEMENT_NAMES.set(params.pool, created);
     return created;
   }
+  function rawStatementNamesFor(params) {
+    const existing = POOL_RAW_STATEMENT_NAMES.get(params.pool);
+    if (existing !== undefined)
+      return existing;
+    const created = createRawStatementNames();
+    POOL_RAW_STATEMENT_NAMES.set(params.pool, created);
+    return created;
+  }
   function buildQueryConfig(params) {
     const values = serializeParams({ values: params.values });
     if (!usePrepared)
@@ -1267,8 +1399,12 @@ function pgAdapter(options) {
     return finalResult({ result }).rows;
   }
   async function runExecuteUnsafe(params) {
+    const name = params.name === undefined ? undefined : assertStatementName({ name: params.name, method: "executeUnsafe" });
+    if (name !== undefined)
+      rawStatementNamesFor({ pool: getPool() }).admit({ name, text: params.text });
     const values = params.values === undefined ? undefined : serializeParamsRaw({ values: params.values });
-    const result = await runMapped(() => params.queryable.query({ text: params.text, values, types: EXACT_TYPES }));
+    const config = name === undefined ? { text: params.text, values, types: EXACT_TYPES } : { name, text: params.text, values, types: EXACT_TYPES };
+    const result = await runMapped(() => params.queryable.query(config));
     observeResult({ scope: params.scope, effect: params.effect, result });
     const final = finalResult({ result });
     return { rows: final.rows, affectedRows: final.rowCount ?? 0 };
@@ -1286,7 +1422,13 @@ function pgAdapter(options) {
     };
     const waitAsLane = (wait) => lane === undefined || pipelines === null ? wait : pipelines.waitAs({ lane, wait });
     const rawClient = {
-      query: (config) => dispatch({ config, batchable: (config.values?.length ?? 0) > 0 || isSingleStatementText({ text: config.text }), ...laneOf, ...finalOf() })
+      query: (config) => dispatch({
+        config,
+        batchable: (config.values?.length ?? 0) > 0 || config.name !== undefined || isSingleStatementText({ text: config.text }),
+        ...config.name === undefined ? {} : { name: config.name },
+        ...laneOf,
+        ...finalOf()
+      })
     };
     const savepointControl = (statement, cleanup) => {
       if (deferred !== null && deferred.routeSavepoint({ text: statement, cleanup }) !== "send")
@@ -1337,10 +1479,10 @@ function pgAdapter(options) {
           if (lane?.group !== undefined)
             throw laneGroupMisuse({ message: "a lane opens no pipeline scope while its group is open" });
           if (!Number.isSafeInteger(count) || count < 1) {
-            throw new VibeError7({ code: "VIBE_VALIDATION", message: "pipeline() needs a positive whole number of lanes", meta: { lanes: count } });
+            throw new VibeError9({ code: "VIBE_VALIDATION", message: "pipeline() needs a positive whole number of lanes", meta: { lanes: count } });
           }
           if (ordered === true && params.ordered !== true) {
-            throw new VibeError7({
+            throw new VibeError9({
               code: "VIBE_VALIDATION",
               message: "pipeline({ ordered: true }) is offered only on a handle that declares orderedPipeline (the top-level or a savepoint handle of a transaction without a deadline, outside a pipeline lane)",
               meta: { ordered: true, reason: "ordered-pipeline-undeclared" }
@@ -1610,7 +1752,10 @@ function pgAdapter(options) {
       const settleRidden = (entry, outcome, commitIndex) => {
         const step = outcome.steps[commitIndex];
         const answeredError = step?.status === "failed" ? mapPgDriverError({ error: step.error }) : undefined;
-        if (step === undefined || answeredError !== undefined && isConnectionLoss({ error: answeredError })) {
+        if (step === undefined && outcome.unsent === true) {
+          commitProgress = "not-sent";
+          entry.state = "skipped";
+        } else if (step === undefined || answeredError !== undefined && isConnectionLoss({ error: answeredError })) {
           commitProgress = "unanswered";
           discard = true;
           budget.close({ outcome: "unknown" });
@@ -1675,7 +1820,12 @@ function pgAdapter(options) {
             return gatherInTurn(dispatchParams);
           return handOver();
         }
-        const statement = dispatchParams.batchable === true ? [{ text: config.text, values: prepareBatchValues({ values: config.values ?? [] }), ...rides && dispatchParams.discardRows === true ? { discardRows: true } : {} }] : [];
+        const statement = dispatchParams.batchable === true ? [{
+          text: config.text,
+          values: prepareBatchValues({ values: config.values ?? [] }),
+          ...dispatchParams.name === undefined ? {} : { name: dispatchParams.name },
+          ...rides && dispatchParams.discardRows === true ? { discardRows: true } : {}
+        }] : [];
         assertReadExecution2({ execution: dispatchParams.execution, effect: "read", support: readCancellation, provider: PROVIDER, stage: "waiting-for-connection" });
         const carriesOpening = !deferred.opened();
         const control = pendingControl ? [...deferred.takeSteps()] : [];
@@ -1826,7 +1976,11 @@ function pgAdapter(options) {
         const control = inTurn ? [] : deferred.takeSteps();
         const openingSteps = carriesOpening ? openingLength : 0;
         const commitIndex = control.length + live.length;
-        const sendBatch = () => runBatch({ client, steps: [...control, ...live.map((entry) => ({ text: entry.text, values: entry.values })), ...rides ? [COMMIT_STEP] : []], types: EXACT_TYPES });
+        const sendBatch = () => runBatch({
+          client,
+          steps: [...control, ...live.map((entry) => entry.name === undefined ? { text: entry.text, values: entry.values } : { text: entry.text, values: entry.values, name: entry.name }), ...rides ? [COMMIT_STEP] : []],
+          types: EXACT_TYPES
+        });
         const batch = inTurn ? new Promise((resolve) => {
           resolve(sendBatch());
         }) : runTurn(sendBatch);
@@ -1862,6 +2016,7 @@ function pgAdapter(options) {
         return {
           text: member.params.config.text,
           values: member.values,
+          ...member.params.name === undefined ? {} : { name: member.params.name },
           ...member.params.execution === undefined || options?.inTurn === true ? {} : { execution: member.params.execution },
           lane: gatheredLane,
           resolve: member.resolve,
@@ -2184,6 +2339,7 @@ function pgAdapter(options) {
           queued.push({
             text: dispatchParams.config.text,
             values,
+            ...dispatchParams.name === undefined ? {} : { name: dispatchParams.name },
             ...dispatchParams.execution === undefined ? {} : { execution: dispatchParams.execution },
             ...alone === true ? { alone: dispatchParams } : {},
             ...dispatchParams.commit === true ? { commit: true } : {},
@@ -2201,7 +2357,18 @@ function pgAdapter(options) {
         return pending;
       };
       const coalescable = (dispatchParams) => capable && budget.totalMs === null && !cancellationQueue && !((client.connectionParameters?.query_timeout ?? 0) > 0) && dispatchParams.batchable === true && dispatchParams.cleanup !== true && dispatchParams.stage === undefined && dispatchParams.sent === undefined && dispatchParams.execution?.cancellation !== "running";
+      let staleNamedStatement = false;
       const dispatch = (dispatchParams) => {
+        const dispatched = route(dispatchParams);
+        if (dispatchParams.config.name === undefined)
+          return dispatched;
+        return dispatched.then(undefined, (error) => {
+          if (isStaleStatementFailure({ error }))
+            staleNamedStatement = true;
+          throw error;
+        });
+      };
+      const route = (dispatchParams) => {
         const lane = dispatchParams.lane?.open === true ? dispatchParams.lane : undefined;
         if (lane !== undefined && dispatchParams.cleanup !== true) {
           if (lane.group !== undefined)
@@ -2416,12 +2583,12 @@ function pgAdapter(options) {
           scope,
           commit: commitProgress,
           rollback,
-          connection: discard ? "discarded" : "returned"
+          connection: discard || staleNamedStatement ? "discarded" : "returned"
         });
       } finally {
         unguard();
         if (!released)
-          client.release(discard);
+          client.release(discard || staleNamedStatement);
       }
     },
     async connect() {
@@ -2548,4 +2715,4 @@ export {
   validateTransactionDeadline2 as validateTransactionDeadline
 };
 
-//# debugId=96B1BE63991D190764756E2164756E21
+//# debugId=7B0EC2D2FB69EE3264756E2164756E21