@vibeorm/adapter-pg 4.1.0 → 4.3.0

package/dist/index.js

@@ -16,8 +16,12 @@ import {
   transactionLifecycleRefusal,
   createSavepointScope,
   engineStatementBudgetMs,
+  findRefusedSetting,
   isSavepointRollbackFailedError,
   readOnlyRequested,
+  readTransactionSettings,
+  renderTransactionSettings,
+  transactionSettingRefusedError,
   runNestedSavepoint,
   runRootScope,
   scopeTurn,
@@ -182,6 +186,26 @@ function firstBatchFailure(params) {
   return;
 }
 
+// packages/adapter-pg/src/client-turns.ts
+function createClientTurns() {
+  let outstanding = 0;
+  let previous = Promise.resolve();
+  const release = () => {
+    outstanding -= 1;
+  };
+  return {
+    run: (send) => {
+      const running = outstanding === 0 ? new Promise((resolve) => {
+        resolve(send());
+      }) : previous.then(send);
+      outstanding += 1;
+      previous = running.then(release, release);
+      return running;
+    },
+    outstanding: () => outstanding
+  };
+}
+
 // packages/adapter-pg/src/read-cancellation.ts
 import pg2 from "pg";
 import { VibeError as VibeError2 } from "@vibeorm/schema";
@@ -221,6 +245,11 @@ 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 PG_SQLSTATE_HINTS = Object.freeze({
+  "26000": NAMED_STATEMENT_POOLER_HINT,
+  "42P05": NAMED_STATEMENT_POOLER_HINT
+});
 var SQLSTATE_PATTERN = /^(?=[A-Z]*\d)[0-9A-Z]{5}$/;
 function readStringField(params) {
   const value = params.source[params.key];
@@ -255,7 +284,9 @@ function mapPgDriverError(params) {
   const reason = sqlstate === undefined ? undefined : PG_SQLSTATE_REASONS[sqlstate];
   if (reason !== undefined)
     meta.reason = reason;
-  const message = readStringField({ source, key: "message" }) ?? (typeof error === "string" ? error : "unknown postgres driver error");
+  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 VibeError({ code, message, meta, cause: error });
 }
 async function runMapped(fn) {
@@ -515,8 +546,18 @@ function placePlanCacheMode(params) {
   url.searchParams.set("options", merged);
   return { connectionString: url.toString(), options: merged };
 }
+function assertIdleTimeout(params) {
+  const { value } = params;
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 2147483647)
+    return value;
+  throw new VibeError3({
+    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" }
+  });
+}
 function buildPoolConfig(params) {
-  const { max, statementTimeout, connectionTimeout } = params;
+  const { max, statementTimeout, connectionTimeout, idleTimeout } = params;
   const placement = placePlanCacheMode({
     connectionString: params.connectionString,
     planCacheMode: params.planCacheMode ?? "auto"
@@ -526,21 +567,43 @@ function buildPoolConfig(params) {
     config.statement_timeout = statementTimeout;
   if (connectionTimeout !== undefined)
     config.connectionTimeoutMillis = connectionTimeout;
+  if (idleTimeout !== undefined)
+    config.idleTimeoutMillis = idleTimeout;
   if (placement.options !== undefined)
     config.options = placement.options;
   return config;
 }
 
 // packages/adapter-pg/src/statement-cache.ts
+import { createHash } from "crypto";
 var DEFAULT_PROMOTE_AFTER = 2;
 var SIGHTINGS_PER_NAME = 4;
+var NAME_PREFIX = "vibeorm_";
+var BASE32_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+function statementNameFor(params) {
+  const digest = createHash("sha256").update(params.text, "utf8").digest();
+  let name = NAME_PREFIX;
+  let buffer = 0;
+  let bits = 0;
+  for (const byte of digest) {
+    buffer = buffer << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      name += BASE32_ALPHABET[buffer >>> bits & 31];
+    }
+    buffer &= (1 << bits) - 1;
+  }
+  if (bits > 0)
+    name += BASE32_ALPHABET[buffer << 5 - bits & 31];
+  return name;
+}
 function createStatementNameCache(params) {
   const max = Math.max(0, params.max);
   const promoteAfter = Math.max(1, params.promoteAfter ?? DEFAULT_PROMOTE_AFTER);
   const sightingsMax = max * SIGHTINGS_PER_NAME;
   const names = new Map;
   const sightings = new Map;
-  let counter = 0;
   return {
     getName(nameParams) {
       const { text } = nameParams;
@@ -562,7 +625,7 @@ function createStatementNameCache(params) {
         return;
       }
       sightings.delete(text);
-      const name = `vibeorm_${counter++}`;
+      const name = statementNameFor({ text });
       names.set(text, name);
       return name;
     },
@@ -575,6 +638,86 @@ function createStatementNameCache(params) {
   };
 }
 
+// packages/adapter-pg/src/timestamp-text.ts
+var DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+var DIGIT_POSITIONS = [0, 1, 2, 3, 5, 6, 8, 9, 11, 12, 14, 15, 17, 18];
+function parsePlainTimestampText(params) {
+  const { text, zoned } = params;
+  const length = text.length;
+  if (length < 19 || text.charCodeAt(4) !== 45 || text.charCodeAt(7) !== 45 || text.charCodeAt(10) !== 32 || text.charCodeAt(13) !== 58 || text.charCodeAt(16) !== 58) {
+    return;
+  }
+  for (let position = 0;position < DIGIT_POSITIONS.length; position++) {
+    const code = text.charCodeAt(DIGIT_POSITIONS[position]);
+    if (code < 48 || code > 57)
+      return;
+  }
+  const year = (text.charCodeAt(0) - 48) * 1000 + (text.charCodeAt(1) - 48) * 100 + (text.charCodeAt(2) - 48) * 10 + (text.charCodeAt(3) - 48);
+  const month = (text.charCodeAt(5) - 48) * 10 + (text.charCodeAt(6) - 48);
+  const day = (text.charCodeAt(8) - 48) * 10 + (text.charCodeAt(9) - 48);
+  const hour = (text.charCodeAt(11) - 48) * 10 + (text.charCodeAt(12) - 48);
+  const minute = (text.charCodeAt(14) - 48) * 10 + (text.charCodeAt(15) - 48);
+  const second = (text.charCodeAt(17) - 48) * 10 + (text.charCodeAt(18) - 48);
+  if (year < 1000 || month < 1 || month > 12 || day < 1 || hour > 23 || minute > 59 || second > 59)
+    return;
+  if (day > 28) {
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = month === 2 ? leap ? 29 : 28 : DAYS_IN_MONTH[month - 1];
+    if (day > days)
+      return;
+  }
+  let index = 19;
+  let milliseconds = 0;
+  if (index < length && text.charCodeAt(index) === 46) {
+    index++;
+    const start = index;
+    while (index < length) {
+      const code = text.charCodeAt(index);
+      if (code < 48 || code > 57)
+        break;
+      if (index - start < 3)
+        milliseconds = milliseconds * 10 + (code - 48);
+      index++;
+    }
+    const digits = index - start;
+    if (digits === 0 || digits > 6)
+      return;
+    if (digits === 1)
+      milliseconds *= 100;
+    else if (digits === 2)
+      milliseconds *= 10;
+  }
+  let offsetMinutes = 0;
+  if (zoned) {
+    if (index + 3 > length)
+      return;
+    const sign = text.charCodeAt(index);
+    if (sign !== 43 && sign !== 45)
+      return;
+    const hours1 = text.charCodeAt(index + 1) - 48;
+    const hours2 = text.charCodeAt(index + 2) - 48;
+    if (hours1 < 0 || hours1 > 9 || hours2 < 0 || hours2 > 9)
+      return;
+    offsetMinutes = (hours1 * 10 + hours2) * 60;
+    index += 3;
+    if (index < length) {
+      if (index + 3 !== length || text.charCodeAt(index) !== 58)
+        return;
+      const minutes1 = text.charCodeAt(index + 1) - 48;
+      const minutes2 = text.charCodeAt(index + 2) - 48;
+      if (minutes1 < 0 || minutes1 > 9 || minutes2 < 0 || minutes2 > 9)
+        return;
+      offsetMinutes += minutes1 * 10 + minutes2;
+      index = length;
+    }
+    if (sign === 45)
+      offsetMinutes = -offsetMinutes;
+  }
+  if (index !== length)
+    return;
+  return new Date(Date.UTC(year, month - 1, day, hour, minute, second, milliseconds) - offsetMinutes * 60000);
+}
+
 // packages/adapter-pg/src/transaction-sql.ts
 import { VibeError as VibeError4 } from "@vibeorm/schema";
 import { refuseNestedTransactionOptions } from "@vibeorm/runtime/adapter-kit";
@@ -616,6 +759,12 @@ function classifyRawTransactionControl(params) {
     return "close";
   return null;
 }
+var NOT_PROVABLY_ONE_STATEMENT = /[;$\u0000]|--|\/\*/;
+var OWN_TURN_VERBS = /^\s*(?:begin|start|commit|end|rollback|abort|savepoint|release|prepare|copy)\b/i;
+function isSingleStatementText(params) {
+  const { text } = params;
+  return text.trim() !== "" && !NOT_PROVABLY_ONE_STATEMENT.test(text) && !OWN_TURN_VERBS.test(text);
+}
 
 // packages/adapter-pg/src/index.ts
 import { createSavepointCounter, nextSavepointName } from "@vibeorm/runtime/adapter-kit";
@@ -633,6 +782,16 @@ var MAX_STATEMENT_TIMEOUT_MS = 2147483647;
 var ignore = () => {
   return;
 };
+function predecessorClosedError() {
+  return new VibeError5({
+    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 VibeError5({ code: "VIBE_INTERNAL", message: `pipeline(): ${params.message}`, meta: { reason: "pipeline-ordered-lane" } });
+}
 function finalResult(params) {
   return Array.isArray(params.result) ? params.result.at(-1) ?? { rows: [], rowCount: 0 } : params.result;
 }
@@ -713,6 +872,8 @@ var DIALECT = "postgres";
 var PROVIDER = "postgresql";
 var WIRE = Object.freeze({ dateTime: "native", json: "parsed", numbers: "native" });
 var ROUND_TRIPS = "network";
+var READ_SNAPSHOT = Object.freeze({ isolationLevel: "RepeatableRead", accessMode: "readOnly" });
+var PIPELINING = "batched";
 var BUDGETS = Object.freeze({
   acquireTimeout: true,
   statementTimeout: "all-statements",
@@ -725,9 +886,14 @@ var TIMESTAMP_OID = 1114;
 var TIMESTAMP_ARRAY_OID = 1115;
 var DATE_OID = 1082;
 var DATE_ARRAY_OID = 1182;
+var TIMESTAMPTZ_OID = 1184;
+var TIMESTAMPTZ_ARRAY_OID = 1185;
 var driverTypeParser = pg3.types.getTypeParser;
 var ZONE_LESS_TEXT = /^\d{4}-\d{2}-\d{2}(?: \d{2}:\d{2}:\d{2}(?:\.\d{1,6})?)?$/;
 function parseZoneLessAsUtc(value) {
+  const plain = parsePlainTimestampText({ text: value, zoned: false });
+  if (plain !== undefined)
+    return plain;
   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);
@@ -746,6 +912,28 @@ function parseZoneLessArrayAsUtc(value) {
   };
   return mapElements(driverTypeParser(TEXT_ARRAY_OID, "text")(value));
 }
+var pgTypesArrayParser = (() => {
+  const candidate = pg3.types.arrayParser;
+  return typeof candidate?.create === "function" ? candidate : undefined;
+})();
+function recogniseBuiltinParser(params) {
+  const parser = driverTypeParser(params.oid, "text");
+  return parser.name === params.name && params.peers.every((peer) => driverTypeParser(peer, "text") === parser) ? parser : undefined;
+}
+var BUILTIN_TIMESTAMPTZ_PARSER = recogniseBuiltinParser({
+  oid: TIMESTAMPTZ_OID,
+  peers: [TIMESTAMP_OID, DATE_OID],
+  name: "parseDate"
+});
+var BUILTIN_TIMESTAMPTZ_ARRAY_PARSER = pgTypesArrayParser === undefined || BUILTIN_TIMESTAMPTZ_PARSER === undefined ? undefined : recogniseBuiltinParser({ oid: TIMESTAMPTZ_ARRAY_OID, peers: [TIMESTAMP_ARRAY_OID, DATE_ARRAY_OID], name: "parseDateArray" });
+function parseTimestamptzText(value) {
+  return parsePlainTimestampText({ text: value, zoned: true }) ?? BUILTIN_TIMESTAMPTZ_PARSER(value);
+}
+function parseTimestamptzArrayText(value) {
+  if (!value)
+    return null;
+  return pgTypesArrayParser.create(value, (entry) => entry !== null ? parseTimestamptzText(entry) : entry).parse();
+}
 var EXACT_TYPES = {
   getTypeParser(oid, format) {
     if (format === undefined || format === "text") {
@@ -755,6 +943,14 @@ var EXACT_TYPES = {
         return parseZoneLessAsUtc;
       if (oid === TIMESTAMP_ARRAY_OID || oid === DATE_ARRAY_OID)
         return parseZoneLessArrayAsUtc;
+      if (oid === TIMESTAMPTZ_OID) {
+        const driver = driverTypeParser(oid, "text");
+        return driver === BUILTIN_TIMESTAMPTZ_PARSER ? parseTimestamptzText : driver;
+      }
+      if (oid === TIMESTAMPTZ_ARRAY_OID) {
+        const driver = driverTypeParser(oid, "text");
+        return driver === BUILTIN_TIMESTAMPTZ_ARRAY_PARSER ? parseTimestamptzArrayText : driver;
+      }
     }
     return driverTypeParser(oid, format);
   }
@@ -779,6 +975,7 @@ function pgAdapter(options) {
   const usePrepared = options?.preparedStatements ?? false;
   const stmtCacheMax = options?.stmtCacheMax ?? 1000;
   const planCacheMode = options?.planCacheMode === undefined ? "auto" : assertPlanCacheMode({ value: options.planCacheMode });
+  const idleTimeout = "pool" in address || options?.idleTimeout === undefined ? undefined : assertIdleTimeout({ value: options.idleTimeout });
   if (planCacheMode !== "auto" && "pool" in address) {
     throw new VibeError5({
       code: "VIBE_CONFIG",
@@ -804,6 +1001,7 @@ function pgAdapter(options) {
       max: options?.max ?? 10,
       ...options?.statementTimeout === undefined ? {} : { statementTimeout: options.statementTimeout },
       ...options?.connectionTimeout === undefined ? {} : { connectionTimeout: options.connectionTimeout },
+      ...idleTimeout === undefined ? {} : { idleTimeout },
       planCacheMode
     });
     const PoolCtor = pg3.Pool;
@@ -850,8 +1048,12 @@ function pgAdapter(options) {
     return { rows: final.rows, affectedRows: final.rowCount ?? 0 };
   }
   function createClientAdapter(params) {
-    const { dispatch, scope, budget, deferred, cancellation } = params;
-    const rawClient = { query: (config) => dispatch({ config, batchable: (config.values?.length ?? 0) > 0 }) };
+    const { dispatch, scope, budget, deferred, cancellation, pipelines, lane } = params;
+    const laneOf = lane === undefined ? {} : { lane };
+    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 })
+    };
     const savepointControl = (statement, cleanup) => {
       if (deferred !== null && deferred.routeSavepoint({ text: statement }) !== "send")
         return;
@@ -859,7 +1061,8 @@ function pgAdapter(options) {
         config: { text: statement },
         stage: "nested",
         batchable: true,
-        ...cleanup ? { cleanup: true } : {}
+        ...cleanup ? { cleanup: true } : {},
+        ...laneOf
       }));
     };
     return {
@@ -869,6 +1072,37 @@ function pgAdapter(options) {
       budgets: BUDGETS,
       readCancellation: cancellation.support,
       roundTrips: ROUND_TRIPS,
+      readSnapshot: READ_SNAPSHOT,
+      pipelining: pipelines === null ? "ordered" : PIPELINING,
+      ...pipelines === null ? {} : {
+        ...params.ordered === true ? { orderedPipeline: true } : {},
+        pipeline: ({ lanes: count, ordered }) => {
+          budget.assertUsable({ stage: "statement" });
+          if (!Number.isSafeInteger(count) || count < 1) {
+            throw new VibeError5({ code: "VIBE_VALIDATION", message: "pipeline() needs a positive whole number of lanes", meta: { lanes: count } });
+          }
+          if (ordered === true && params.ordered !== true) {
+            throw new VibeError5({
+              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 or a timeout, outside a pipeline lane)",
+              meta: { ordered: true, reason: "ordered-pipeline-undeclared" }
+            });
+          }
+          const laneHandle = (opened) => ({
+            adapter: createClientAdapter({ dispatch, scope, budget, deferred, cancellation, pipelines, lane: opened }),
+            close: () => {
+              pipelines.close(opened);
+            },
+            ...opened.order === undefined ? {} : {
+              follow: () => {
+                budget.assertUsable({ stage: "statement" });
+                return laneHandle(pipelines.follow(opened));
+              }
+            }
+          });
+          return (ordered === true ? pipelines.openOrdered(count) : pipelines.open(count)).map(laneHandle);
+        }
+      },
       rowChanges: () => {
         budget.assertUsable({ stage: "statement" });
         return readRowChanges({ scope });
@@ -877,29 +1111,35 @@ function pgAdapter(options) {
         return runReadExecution({ ...execParams, support: cancellation.support, provider: PROVIDER, run: async () => {
           const turn = scopeTurn({ scope });
           if (turn !== undefined)
-            await turn;
+            await waitAsLane(turn);
           budget.assertUsable({ stage: "statement" });
           assertReadExecution2({ ...execParams, support: cancellation.support, provider: PROVIDER, stage: "waiting-for-connection" });
-          const queryable = { query: (config) => dispatch({ config, batchable: execParams.execution?.cancellation !== "running", execution: execParams.execution, onReadControl: execParams.onReadControl }) };
+          const queryable = { query: (config) => dispatch({ config, batchable: execParams.execution?.cancellation !== "running", execution: execParams.execution, onReadControl: execParams.onReadControl, ...laneOf }) };
           return runExecute({ queryable, scope, ...execParams }).catch((error) => abortTransactionOnServerFailure({ scope, error }));
         } });
       },
       async executeUnsafe(execParams) {
         const turn = scopeTurn({ scope });
         if (turn !== undefined)
-          await turn;
+          await waitAsLane(turn);
         budget.assertUsable({ stage: "statement" });
         return runExecuteUnsafe({ queryable: rawClient, scope, ...execParams }).catch((error) => abortTransactionOnServerFailure({ scope, error }));
       },
       async transaction(fn, nestedOptions) {
         refuseNestedTransactionOptions({ options: nestedOptions, provider: PROVIDER });
         budget.assertUsable({ stage: "nested" });
+        pipelines?.flush();
+        const leave = lane === undefined || pipelines === null ? ignore : pipelines.enter(lane);
         return runNestedSavepoint({
           scope,
           execute: (statement) => savepointControl(statement, false),
           cleanup: (statement) => savepointControl(statement, true),
-          body: (child) => fn(createClientAdapter({ dispatch, scope: child, budget, deferred, cancellation }))
-        });
+          body: (child) => {
+            leave();
+            const ordered = lane === undefined && params.ordered === true ? { ordered: true } : {};
+            return fn(createClientAdapter({ dispatch, scope: child, budget, deferred, cancellation, pipelines, ...laneOf, ...ordered }));
+          }
+        }).finally(leave);
       },
       async connect() {
         budget.assertUsable({ stage: "statement" });
@@ -1034,7 +1274,8 @@ function pgAdapter(options) {
       validateTransactionDeadline({
         options: transactionOptions,
         support: BUDGETS.transactionDeadline,
-        provider: PROVIDER
+        provider: PROVIDER,
+        settings: "transaction-local"
       });
       const openingOptions = {
         isolationLevel: transactionOptions?.isolationLevel,
@@ -1042,7 +1283,19 @@ function pgAdapter(options) {
         timeout: transactionOptions?.timeout
       };
       const openText = openTransactionStatement(openingOptions);
+      const settings = readTransactionSettings({ settings: transactionOptions?.settings, provider: PROVIDER });
+      const settingsStatement = settings.length === 0 ? undefined : renderTransactionSettings({ settings });
       const client = await runMapped(() => getPool().connect());
+      const turns = createClientTurns();
+      const onClient = {
+        query: (config) => turns.run(() => client.query(config)),
+        get pipeline() {
+          return client.pipeline;
+        },
+        get connectionParameters() {
+          return client.connectionParameters;
+        }
+      };
       let connectionFailure;
       const unguard = guardBackgroundErrors({
         client,
@@ -1054,7 +1307,7 @@ function pgAdapter(options) {
       const scope = createSavepointScope();
       const budget = startTransactionBudget({ options: transactionOptions, provider: PROVIDER });
       const capable = supportsBatch({ client });
-      const deferOpening = capable && (openingOptions.timeout === undefined || openingOptions.timeout <= MAX_STATEMENT_TIMEOUT_MS);
+      const deferOpening = settingsStatement === undefined && capable && (openingOptions.timeout === undefined || openingOptions.timeout <= MAX_STATEMENT_TIMEOUT_MS);
       const opening = deferOpening ? [beginStatement(openingOptions), ...openingOptions.timeout === undefined ? [] : [statementTimeoutStatement({ timeout: openingOptions.timeout })]] : [];
       const deferred = createDeferredControl({ opening });
       let openingFailure;
@@ -1064,7 +1317,7 @@ function pgAdapter(options) {
         const handOver = () => {
           assertReadExecution2({ execution: dispatchParams.execution, effect: "read", support: readCancellation, provider: PROVIDER, stage: "waiting-for-connection" });
           dispatchParams.sent?.();
-          return cancellation.run({ config, execution: dispatchParams.execution, onReadControl: dispatchParams.onReadControl, send: () => client.query(config) });
+          return cancellation.run({ config, execution: dispatchParams.execution, onReadControl: dispatchParams.onReadControl, send: () => onClient.query(config) });
         };
         if (cleanup !== true && cancellationAttempted)
           throw transactionAbortedError({ cause: readCancelledError2({ stage: "running" }) });
@@ -1083,7 +1336,7 @@ function pgAdapter(options) {
           if (bound === undefined)
             return handOver();
           const stage = dispatchParams.stage ?? "statement";
-          return runMapped(() => client.query({ text: bound })).then(() => {
+          return runMapped(() => onClient.query({ text: bound })).then(() => {
             budget.assertUsable({ stage });
             return handOver();
           });
@@ -1100,7 +1353,7 @@ function pgAdapter(options) {
         assertReadExecution2({ execution: dispatchParams.execution, effect: "read", support: readCancellation, provider: PROVIDER, stage: "waiting-for-connection" });
         if (statement.length > 0)
           dispatchParams.sent?.();
-        const burst = runBatch({ client, steps: [...control.map((text) => ({ text })), ...statement], types: EXACT_TYPES }).then((outcome) => {
+        const burst = turns.run(() => runBatch({ client, steps: [...control.map((text) => ({ text })), ...statement], types: EXACT_TYPES })).then((outcome) => {
           const failure = firstBatchFailure({ outcome });
           if (failure !== undefined) {
             if (failure.index < openingSteps || outcome.transportError !== undefined && openingSteps > 0) {
@@ -1122,18 +1375,358 @@ function pgAdapter(options) {
         }
         return burst;
       };
-      const send = (dispatchParams) => {
+      const guarded = (run) => {
         try {
-          return sendWithControl(dispatchParams);
+          return run();
         } catch (error) {
           return Promise.reject(error);
         }
       };
+      const send = (dispatchParams) => guarded(() => sendWithControl(dispatchParams));
       let tail = Promise.resolve();
       const activeDispatches = new Set;
       let cancellationQueue = false;
+      const lanes = new Set;
+      let queued = [];
+      const settleQueued = (entry, outcome) => {
+        if (entry.settled)
+          return;
+        entry.settled = true;
+        entry.lane.waiting -= 1;
+        if ("result" in outcome) {
+          entry.resolve(outcome.result);
+        } else {
+          entry.failure = outcome.error;
+          entry.reject(outcome.error);
+        }
+      };
+      const distributeBurst = (burst) => {
+        const { outcome, live, controlSteps, openingSteps } = burst;
+        const failure = firstBatchFailure({ outcome });
+        if (failure === undefined) {
+          live.forEach((entry, index) => {
+            const step = outcome.steps[controlSteps + index];
+            settleQueued(entry, { result: step?.status === "ok" ? step.result : { rows: [], rowCount: 0 } });
+          });
+          return;
+        }
+        const mapped = mapPgDriverError({ error: failure.error });
+        if (failure.index < openingSteps || outcome.transportError !== undefined && openingSteps > 0)
+          openingFailure = mapped;
+        if (typeof mapped.meta.sqlstate === "string")
+          markTransactionAborted({ scope, cause: mapped });
+        const answered = outcome.transportError === undefined;
+        if (failure.index < controlSteps) {
+          const later = answered || openingFailure !== undefined ? transactionAbortedError({ cause: openingFailure ?? mapped }) : mapped;
+          live.forEach((entry, index) => {
+            settleQueued(entry, { error: index === 0 ? mapped : later });
+          });
+          return;
+        }
+        let abortCause = mapped;
+        live.forEach((entry, index) => {
+          const position = controlSteps + index;
+          const step = outcome.steps[position];
+          if (step === undefined) {
+            settleQueued(entry, { error: position === failure.index || openingFailure === undefined ? mapped : transactionAbortedError({ cause: openingFailure }) });
+          } else if (step.status === "ok") {
+            settleQueued(entry, { result: step.result });
+          } else if (step.status === "failed") {
+            const error = position === failure.index ? mapped : mapPgDriverError({ error: step.error });
+            if (typeof error.meta.sqlstate === "string")
+              abortCause = error;
+            settleQueued(entry, { error });
+          } else {
+            settleQueued(entry, { error: transactionAbortedError({ cause: abortCause }) });
+          }
+        });
+      };
+      const sendRefusal = () => cancellationAttempted ? transactionAbortedError({ cause: readCancelledError2({ stage: "running" }) }) : openingFailure !== undefined ? transactionAbortedError({ cause: openingFailure }) : scope.state.poisoned ?? (scope.state.aborted === null ? undefined : transactionAbortedError({ cause: scope.state.aborted.cause }));
+      const sendQueued = (entries) => {
+        const refusal = sendRefusal();
+        const live = [];
+        for (const entry of entries) {
+          if (refusal !== undefined)
+            settleQueued(entry, { error: refusal });
+          else if (entry.execution?.signal?.aborted === true)
+            settleQueued(entry, { error: readCancelledError2({ stage: "waiting-for-connection" }) });
+          else
+            live.push(entry);
+        }
+        if (live.length === 0)
+          return Promise.resolve();
+        const carriesOpening = !deferred.opened();
+        const control = deferred.take();
+        const openingSteps = carriesOpening ? opening.length : 0;
+        const burst = turns.run(() => runBatch({ client, steps: [...control.map((text) => ({ text })), ...live.map((entry) => ({ text: entry.text, values: entry.values }))], types: EXACT_TYPES })).then((outcome) => {
+          distributeBurst({ outcome, live, controlSteps: control.length, openingSteps });
+        }).then(undefined, (error) => {
+          if (openingSteps > 0)
+            openingFailure ??= mapPgDriverError({ error });
+          for (const entry of live)
+            settleQueued(entry, { error });
+        });
+        if (carriesOpening) {
+          const settled = burst.then(() => {
+            if (inFlight === settled)
+              inFlight = null;
+          });
+          inFlight = settled;
+        }
+        return burst;
+      };
+      const sendAlone = (entry, alone) => {
+        const refusal = sendRefusal();
+        if (refusal !== undefined) {
+          settleQueued(entry, { error: refusal });
+          return Promise.resolve();
+        }
+        return dispatchOrdinary(alone).then((result) => {
+          settleQueued(entry, { result });
+        }, (error) => {
+          const mapped = mapPgDriverError({ error });
+          if (typeof mapped.meta.sqlstate === "string")
+            markTransactionAborted({ scope, cause: mapped });
+          settleQueued(entry, { error });
+        });
+      };
+      const prefixOf = (lane) => {
+        const order = lane.order;
+        if (order === undefined)
+          return "issued";
+        let state = "issued";
+        for (let index = 0;index < order.index; index++) {
+          const earlier = order.scope.lanes[index];
+          if (earlier.order.issued > 0)
+            continue;
+          if (!earlier.open)
+            return "closed";
+          state = "open";
+        }
+        return state;
+      };
+      const refuseOrphaned = () => {
+        if (!queued.some((entry) => prefixOf(entry.lane) === "closed"))
+          return;
+        const kept = [];
+        for (const entry of queued) {
+          if (prefixOf(entry.lane) === "closed")
+            settleQueued(entry, { error: predecessorClosedError() });
+          else
+            kept.push(entry);
+        }
+        queued = kept;
+      };
+      const orderedSend = (entries, send) => () => {
+        const live = [];
+        for (const entry of entries) {
+          const failed = entry.lane.order?.scope.failed;
+          if (failed === undefined)
+            live.push(entry);
+          else
+            settleQueued(entry, { error: sendRefusal() ?? transactionAbortedError({ cause: failed.cause }) });
+        }
+        if (live.length === 0)
+          return Promise.resolve();
+        return send(live).then(() => {
+          for (const entry of live) {
+            const order = entry.lane.order;
+            if (order !== undefined && entry.failure !== undefined)
+              order.scope.failed ??= { cause: mapPgDriverError({ error: entry.failure }) };
+          }
+        });
+      };
+      let orderedTail = null;
+      const flushOrdered = () => {
+        refuseOrphaned();
+        const ready = [];
+        const held = [];
+        for (const entry of queued)
+          (prefixOf(entry.lane) === "issued" ? ready : held).push(entry);
+        queued = held;
+        if (ready.length === 0)
+          return;
+        ready.sort((first, second) => (first.lane.order?.index ?? 0) - (second.lane.order?.index ?? 0));
+        const sends = [];
+        let run = [];
+        for (const entry of ready) {
+          const alone = entry.alone;
+          if (alone === undefined) {
+            run.push(entry);
+            continue;
+          }
+          if (run.length > 0) {
+            sends.push(orderedSend(run, sendQueued));
+            run = [];
+          }
+          sends.push(orderedSend([entry], () => sendAlone(entry, alone)));
+        }
+        if (run.length > 0)
+          sends.push(orderedSend(run, sendQueued));
+        const before = [orderedTail, inFlight].filter((wait) => wait !== null);
+        let chain = before.length === 0 ? sends.shift()() : Promise.all(before).then(ignore);
+        for (const next of sends)
+          chain = chain.then(next);
+        const tail = chain;
+        orderedTail = tail;
+        tail.then(() => {
+          if (orderedTail === tail)
+            orderedTail = null;
+        });
+      };
+      const flushQueue = () => {
+        if (queued.length === 0)
+          return;
+        if (queued.some((entry) => entry.lane.order !== undefined)) {
+          flushOrdered();
+          return;
+        }
+        const entries = queued;
+        queued = [];
+        if (inFlight === null)
+          sendQueued(entries);
+        else
+          inFlight.then(() => {
+            sendQueued(entries);
+          });
+      };
+      const flushIfReady = () => {
+        if (queued.length === 0)
+          return;
+        for (const open of lanes)
+          if (open.waiting === 0)
+            return;
+        flushQueue();
+      };
+      const pipelines = {
+        open: (count) => Array.from({ length: count }, () => {
+          const opened = { open: true, waiting: 0 };
+          lanes.add(opened);
+          return opened;
+        }),
+        openOrdered: (count) => {
+          const ordered = { lanes: [] };
+          for (let index = 0;index < count; index++) {
+            const opened = { open: true, waiting: 0, order: { scope: ordered, index, issued: 0, followed: false } };
+            ordered.lanes.push(opened);
+            lanes.add(opened);
+          }
+          return [...ordered.lanes];
+        },
+        follow: (lane) => {
+          const order = lane.order;
+          if (order === undefined)
+            throw orderedLaneMisuse({ message: "follow() exists only on the lanes of an ordered scope" });
+          if (!lane.open)
+            throw orderedLaneMisuse({ message: "follow() on a closed lane" });
+          if (order.followed || order.scope.lanes.at(-1) !== lane)
+            throw orderedLaneMisuse({ message: "follow() opens one lane after the LAST lane of its scope" });
+          if (order.issued > 0)
+            throw orderedLaneMisuse({ message: "follow() must come before the lane issues its statement" });
+          order.followed = true;
+          const next = { open: true, waiting: 0, order: { scope: order.scope, index: order.scope.lanes.length, issued: 0, followed: false } };
+          order.scope.lanes.push(next);
+          lanes.add(next);
+          return next;
+        },
+        close: (lane) => {
+          if (!lane.open)
+            return;
+          lane.open = false;
+          lanes.delete(lane);
+          if (lane.order !== undefined)
+            refuseOrphaned();
+          flushIfReady();
+        },
+        waitAs: ({ lane, wait }) => {
+          if (!lane.open)
+            return wait;
+          lane.waiting += 1;
+          flushIfReady();
+          return wait.then((value) => {
+            lane.waiting -= 1;
+            return value;
+          }, (error) => {
+            lane.waiting -= 1;
+            throw error;
+          });
+        },
+        enter: (lane) => {
+          if (!lane.open)
+            return ignore;
+          lane.waiting += 1;
+          flushIfReady();
+          let left = false;
+          return () => {
+            if (left)
+              return;
+            left = true;
+            lane.waiting -= 1;
+          };
+        },
+        flush: flushQueue
+      };
+      const endPipeline = () => {
+        for (const open of lanes)
+          open.open = false;
+        lanes.clear();
+        flushQueue();
+      };
+      const enqueue = (dispatchParams, lane, alone) => {
+        if (cancellationAttempted)
+          throw transactionAbortedError({ cause: readCancelledError2({ stage: "running" }) });
+        if (openingFailure !== undefined)
+          throw transactionAbortedError({ cause: openingFailure });
+        assertReadExecution2({ execution: dispatchParams.execution, effect: "read", support: readCancellation, provider: PROVIDER, stage: "waiting-for-connection" });
+        const values = alone === true ? [] : prepareBatchValues({ values: dispatchParams.config.values ?? [] });
+        const pending = new Promise((resolve, reject) => {
+          lane.waiting += 1;
+          queued.push({
+            text: dispatchParams.config.text,
+            values,
+            ...dispatchParams.execution === undefined ? {} : { execution: dispatchParams.execution },
+            ...alone === true ? { alone: dispatchParams } : {},
+            lane,
+            resolve,
+            reject,
+            settled: false
+          });
+        });
+        if (lane.order !== undefined)
+          lane.order.issued += 1;
+        activeDispatches.add(pending);
+        pending.then(() => activeDispatches.delete(pending), () => activeDispatches.delete(pending));
+        flushIfReady();
+        return pending;
+      };
+      const coalescable = (dispatchParams) => capable && budget.totalMs === null && !cancellationQueue && dispatchParams.batchable === true && dispatchParams.cleanup !== true && dispatchParams.stage === undefined && dispatchParams.sent === undefined && dispatchParams.execution?.cancellation !== "running";
       const dispatch = (dispatchParams) => {
+        const lane = dispatchParams.lane?.open === true ? dispatchParams.lane : undefined;
+        const order = lane?.order;
+        if (lane !== undefined && order !== undefined && dispatchParams.cleanup !== true) {
+          return guarded(() => {
+            if (order.followed && order.issued > 0)
+              throw orderedLaneMisuse({ message: "a lane that has a follower may issue ONE statement" });
+            return coalescable(dispatchParams) ? enqueue(dispatchParams, lane) : enqueue(dispatchParams, lane, true);
+          });
+        }
+        if (lane !== undefined && coalescable(dispatchParams))
+          return guarded(() => enqueue(dispatchParams, lane));
+        if (lane === undefined)
+          return dispatchOrdinary(dispatchParams);
+        const leave = pipelines.enter(lane);
+        flushQueue();
+        return dispatchOrdinary(dispatchParams).then((result) => {
+          leave();
+          return result;
+        }, (error) => {
+          leave();
+          throw error;
+        });
+      };
+      const dispatchOrdinary = (dispatchParams) => {
         if (dispatchParams.execution?.cancellation === "running" && !cancellationQueue) {
+          flushQueue();
           cancellationQueue = true;
           tail = Promise.allSettled([...activeDispatches]);
         }
@@ -1150,7 +1743,7 @@ function pgAdapter(options) {
       let discard = false;
       let released = false;
       let cancellationAttempted = false;
-      const cancellation = createPgReadCancellation({ connectionString: cancellationAddress, target: client, terminate: () => {
+      const cancellation = createPgReadCancellation({ connectionString: cancellationAddress, target: onClient, terminate: () => {
         if (!released) {
           released = true;
           client.release(true);
@@ -1161,13 +1754,57 @@ function pgAdapter(options) {
         markTransactionAborted({ scope, cause: readCancelledError2({ stage: "running" }) });
       } });
       let commitProgress = "not-sent";
+      let openingRollback;
+      const openWithSettings = async (statement) => {
+        let failed;
+        if (capable) {
+          const control = [beginStatement(openingOptions), ...openingOptions.timeout === undefined ? [] : [statementTimeoutStatement({ timeout: openingOptions.timeout })]];
+          const outcome = await turns.run(() => runBatch({
+            client,
+            steps: [...control.map((text) => ({ text })), { text: statement.text, values: prepareBatchValues({ values: statement.values }) }],
+            types: EXACT_TYPES
+          }));
+          const failure = firstBatchFailure({ outcome });
+          if (failure === undefined)
+            return;
+          if (failure.index < control.length || outcome.transportError !== undefined)
+            throw mapPgDriverError({ error: failure.error });
+          failed = { error: failure.error };
+        } else {
+          await runMapped(() => onClient.query({ text: openText }));
+          failed = await onClient.query({ text: statement.text, values: [...statement.values] }).then(() => {
+            return;
+          }, (error) => ({ error }));
+          if (failed === undefined)
+            return;
+        }
+        const cause = mapPgDriverError({ error: failed.error });
+        if (typeof cause.meta.sqlstate !== "string")
+          throw cause;
+        openingRollback = await onClient.query({ text: "ROLLBACK" }).then(() => "acknowledged", () => "failed");
+        if (openingRollback === "failed")
+          discard = true;
+        const setting = findRefusedSetting({ settings, cause });
+        throw transactionSettingRefusedError({ provider: PROVIDER, settings, setting, cause });
+      };
       try {
-        if (!deferOpening)
-          await runMapped(() => client.query({ text: openText }));
+        if (settingsStatement !== undefined)
+          await openWithSettings(settingsStatement);
+        else if (!deferOpening)
+          await runMapped(() => onClient.query({ text: openText }));
         const result = await runRootScope({
           scope,
-          body: () => fn(createClientAdapter({ dispatch, scope, budget, deferred: capable ? deferred : null, cancellation }))
+          body: () => fn(createClientAdapter({
+            dispatch,
+            scope,
+            budget,
+            deferred: capable ? deferred : null,
+            cancellation,
+            pipelines: capable ? pipelines : null,
+            ordered: capable && budget.totalMs === null && openingOptions.timeout === undefined && !((client.connectionParameters?.query_timeout ?? 0) > 0)
+          }))
         });
+        endPipeline();
         budget.assertUsable({ stage: "commit" });
         if (!deferred.opened()) {
           budget.close({ outcome: "committed" });
@@ -1203,13 +1840,16 @@ function pgAdapter(options) {
         budget.close({ outcome: "committed" });
         return result;
       } catch (error) {
+        endPipeline();
         if (isSavepointRollbackFailedError(error) || scope.state.poisoned !== null) {
           discard = true;
           budget.close({ outcome: "unknown" });
         }
         let rollback = "not-needed";
         try {
-          if (deferred.opened()) {
+          if (openingRollback !== undefined)
+            rollback = openingRollback;
+          else if (deferred.opened()) {
             await dispatch({ config: { text: "ROLLBACK" }, cleanup: true });
             rollback = "acknowledged";
           }
@@ -1244,7 +1884,10 @@ function pgAdapter(options) {
     budgets: BUDGETS,
     readCancellation,
     roundTrips: ROUND_TRIPS,
+    readSnapshot: READ_SNAPSHOT,
+    pipelining: PIPELINING,
     transactionOutcome: "reported",
+    transactionSettings: "transaction-local",
     withSession({ run }) {
       return lifecycle.admit({ run: () => root.withSession({ run: (executor) => lifecycle.inCallback({ run: () => run(executor) }) }) });
     },
@@ -1297,4 +1940,4 @@ export {
   validateTransactionDeadline2 as validateTransactionDeadline
 };
 
-//# debugId=3DBA8F0584DC025664756E2164756E21
+//# debugId=FB5284F22EED8D0A64756E2164756E21