@vibeorm/adapter-pg 5.1.0 → 5.2.1

package/README.md

@@ -55,7 +55,7 @@ const db = VibeClient({ adapter: pgAdapter({ pool }) });
 | `cancellationConnectionString` | `string` | Owned `connectionString`; none for an injected `pool` | Separate control endpoint for running read cancellation; same PostgreSQL server/database, with permission to signal the target role |
 | `preparedStatements` | `boolean` | `false` | Send ORM-path queries as named prepared statements. Measured −17…−25 % on reads and −6 % on a by-key update (see below). Off by default because of transaction-mode poolers — turn it on for direct connections, session pooling, or PgBouncer 1.21+ with `max_prepared_statements > 0`. Works with an injected `pool` too; the name budget (`stmtCacheMax`) then belongs to that pool and is shared by every adapter on it |
 | `stmtCacheMax` | `number` | `1000` | Budget of prepared-statement names per pool. Names never evict (an evicted name stays prepared on the backend), so this bounds server-side retention per connection; a text arriving after the budget is spent runs unnamed |
-| `planCacheMode` | `"auto" \| "force_custom_plan" \| "force_generic_plan"` | `"auto"` | PostgreSQL `plan_cache_mode` for every connection of the pool the adapter builds; sent in the `options` startup parameter, merged with an `options` the URL already carries (a URL that sets `plan_cache_mode` itself wins). Refused with `VIBE_CONFIG` next to a caller-supplied `pool` |
+| `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), or with `PGOPTIONS` when the URL has none. Refused with `VIBE_CONFIG` next to a caller-supplied `pool` |
 
 ### A database far away
 
@@ -137,6 +137,18 @@ Outside transactions the adapter declares `connectionGroup` (when the driver can
 
 A raw script that produces multiple PostgreSQL results returns only the **final command's** rows and affected-row count. Earlier results are not concatenated or summed; a final DDL command returns empty rows and zero affected rows.
 
+### Explicit deferred work
+
+Transaction clients accept `tx.$queueRaw({ query, name? })`, where `query` is a bound `sql` fragment. Queued statements keep insertion order and travel before the next eligible statement, or before COMMIT when no statement follows. Each remains a separate SQL statement, so under READ COMMITTED a load after a lock wait takes its snapshot after acquisition. A queued failure rejects the companion statement and the transaction with the queued statement's typed error, even if the callback catches the companion rejection.
+
+`$lazy(() => db.model.findMany(...))`, `$queryRawLazy({ query, access, name? })` and `$executeRawLazy({ query, name? })` stay unsent until awaited or explicitly claimed by `$all`, an array transaction or `commitWith`. Existing raw calls remain immediate. Search and `vector.nearest` contribute lazy reads; `vector.set` contributes a write. Inside an existing transaction, `$all` preserves object-key enumeration order, including locking reads. Eligible one-statement members still share an ordered batch.
+
+`commitWith` accepts an ordered final-item list. Eligible application writes and a following flush can share the closing batch with COMMIT. Result-bearing tail items settle only after transaction completion, in list order. A failure rejects every item with the transaction's same error. A refusable client-side reply keeps COMMIT separate. Nested array transactions remain savepoints and never infer that they are final.
+
+Count-only bulk writes accept `expect: n` on PostgreSQL. The SQL guard checks direct affected rows and raises `VIBE_ROW_COUNT_MISMATCH` before COMMIT when the count differs. Unsupported or multi-statement shapes refuse instead of substituting a client-only check.
+
+`tx.$advisoryLocks({ keys, mode?, defer? })` takes sorted, deduplicated signed 64-bit keys in one statement. The immediate form confirms acquisition. `defer: true` confirms enqueueing only, with acquisition before the next statement. The top-level `advisoryLocks` transaction option queues the same statement before the first load. These explicit boundaries add no timer or microtask gathering window. Existing deadline, driver-timeout and pipeline capability checks still decide whether wire batching is safe.
+
 ## Parameter serialization: two paths
 
 `pg` turns a JS array into a PostgreSQL array literal natively, which is what a raw query wants but not what the ORM path can assume. The adapter therefore keeps two helpers:

package/dist/index.d.ts

@@ -179,7 +179,8 @@ export type PgAdapterSettings = {
      * 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
+     * `plan_cache_mode` itself wins), or with `PGOPTIONS` when it carries none.
+     * 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.
      */

package/dist/index.js

@@ -792,13 +792,14 @@ function placePlanCacheMode(params) {
   if (planCacheMode === "auto")
     return { connectionString, options: undefined };
   const setting = `-c plan_cache_mode=${planCacheMode}`;
+  const configOptions = [params.ambientOptions?.trim() ?? "", setting].filter(Boolean).join(" ");
   if (connectionString === undefined || !URL.canParse(connectionString)) {
-    return { connectionString, options: setting };
+    return { connectionString, options: configOptions };
   }
   const url = new URL(connectionString);
   const existing = url.searchParams.get("options");
   if (existing === null) {
-    return { connectionString, options: setting };
+    return { connectionString, options: configOptions };
   }
   if (/(^|\s)-c\s*plan_cache_mode=/.test(existing)) {
     return { connectionString, options: undefined };
@@ -831,7 +832,8 @@ function buildPoolConfig(params) {
   const { max, min, statementTimeout, connectionTimeout, idleTimeout } = params;
   const placement = placePlanCacheMode({
     connectionString: params.connectionString,
-    planCacheMode: params.planCacheMode ?? "auto"
+    planCacheMode: params.planCacheMode ?? "auto",
+    ...params.ambientOptions === undefined ? {} : { ambientOptions: params.ambientOptions }
   });
   const config = { connectionString: placement.connectionString, max };
   if (min !== undefined)
@@ -1352,7 +1354,8 @@ function pgAdapter(options) {
       ...options?.statementTimeout === undefined ? {} : { statementTimeout: options.statementTimeout },
       ...options?.connectionTimeout === undefined ? {} : { connectionTimeout: options.connectionTimeout },
       ...idleTimeout === undefined ? {} : { idleTimeout },
-      planCacheMode
+      planCacheMode,
+      ...process.env.PGOPTIONS === undefined ? {} : { ambientOptions: process.env.PGOPTIONS }
     });
     const PoolCtor = pg3.Pool;
     pool = new PoolCtor(config);
@@ -1452,6 +1455,25 @@ function pgAdapter(options) {
       pipelining: pipelines === null ? "ordered" : PIPELINING,
       connectionIdentity: connection,
       ...params.topLevel !== true || deferred === null ? {} : {
+        queueStatement: (statement) => {
+          budget.assertUsable({ stage: "statement" });
+          if (scope.state.open !== null || final !== undefined)
+            throw new VibeError9({ code: "VIBE_VALIDATION", message: "Queue statements on the active transaction handle, outside an open savepoint", meta: { reason: "queue-scope" } });
+          scopeTurn({ scope });
+          const name = statement.name === undefined ? undefined : assertStatementName({ name: statement.name, method: "$queueRaw" });
+          if (name !== undefined)
+            rawStatementNamesFor({ pool: getPool() }).admit({ name, text: statement.text });
+          deferred.defer({
+            text: statement.text,
+            values: prepareBatchValues({ values: serializeParamsRaw({ values: [...statement.values] }) }),
+            ...name === undefined ? {} : { name },
+            required: true,
+            onError: statement.onError,
+            ...statement.onStart === undefined ? {} : { onStart: statement.onStart },
+            ...statement.onSettled === undefined ? {} : { onSettled: statement.onSettled },
+            onSuccess: () => observeRowChanges({ scope, count: statement.effect === "read" ? 0 : "unknown" })
+          });
+        },
         deferStatement: (statement) => {
           budget.assertUsable({ stage: "statement" });
           deferred.defer({ text: statement.text, values: prepareBatchValues({ values: statement.values }) });
@@ -1744,6 +1766,26 @@ function pgAdapter(options) {
         return transactionSettingRefusedError({ provider: PROVIDER, settings, setting: findRefusedSetting({ settings, cause: mapped }), cause: mapped, deferred: true });
       };
       let openingFailure;
+      let queuedFailure;
+      const observeDeferred = (control, outcome) => {
+        for (let index = 0;index < control.length; index++) {
+          const entry = control[index];
+          const step = outcome.steps[index];
+          if (step?.status === "ok") {
+            entry.onSuccess?.();
+            entry.onSettled?.({ status: "fulfilled", value: { rows: step.result.rows, affectedRows: step.result.rowCount ?? 0 } });
+          } else {
+            const origin = mapPgDriverError({ error: step?.status === "failed" ? step.error : firstBatchFailure({ outcome })?.error ?? outcome.transportError });
+            if (entry.required === true && step?.status === "failed") {
+              queuedFailure ??= origin;
+              if (entry.name !== undefined && isStaleStatementFailure({ error: queuedFailure }))
+                staleNamedStatement = true;
+              entry.onError?.(queuedFailure);
+            }
+            entry.onSettled?.({ status: "rejected", reason: queuedFailure ?? origin });
+          }
+        }
+      };
       let inFlight = null;
       const commits = capable && budget.totalMs === null && !((client.connectionParameters?.query_timeout ?? 0) > 0);
       let ridden;
@@ -1789,6 +1831,8 @@ function pgAdapter(options) {
           dispatchParams.sent?.();
           return cancellation.run({ config, execution: dispatchParams.execution, onReadControl: dispatchParams.onReadControl, send: () => onClient.query(config) });
         };
+        if (cleanup !== true && queuedFailure !== undefined)
+          throw queuedFailure;
         if (cleanup !== true && cancellationAttempted)
           throw transactionAbortedError2({ cause: readCancelledError2({ stage: "running" }) });
         if (cleanup !== true && openingFailure !== undefined)
@@ -1835,11 +1879,16 @@ function pgAdapter(options) {
         if (statement.length > 0)
           dispatchParams.sent?.();
         const commitIndex = control.length + statement.length;
-        const batch = runTurn(() => runBatch({ client, steps: [...control, ...statement, ...rides ? [COMMIT_STEP] : []], types: EXACT_TYPES }));
+        const batch = runTurn(() => {
+          for (const step of control)
+            step.onStart?.();
+          return runBatch({ client, steps: [...control, ...statement, ...rides ? [COMMIT_STEP] : []], types: EXACT_TYPES });
+        });
         if (rides)
           trackRidden(batch, commitIndex);
         const burst = batch.then((received) => {
           const outcome = rides ? beforeCommit({ outcome: received, commitIndex }) : received;
+          observeDeferred(control, outcome);
           const failure = firstBatchFailure({ outcome });
           if (failure !== undefined) {
             const openingFailed = failure.index < openingSteps || outcome.transportError !== undefined && openingSteps > 0;
@@ -1851,6 +1900,10 @@ function pgAdapter(options) {
               if (typeof mapped.meta.sqlstate === "string")
                 markTransactionAborted({ scope, cause: mapped });
             }
+            if (dispatchParams.stage === "commit" && failure.index < control.length && outcome.transportError === undefined)
+              commitProgress = "not-sent";
+            if (queuedFailure !== undefined)
+              throw queuedFailure;
             throw openingFailed && settingsDeferred && failure.index === opening.length && openingFailure !== undefined ? openingFailure : failure.error;
           }
           if (statement.length === 0)
@@ -1902,7 +1955,7 @@ function pgAdapter(options) {
           });
           return;
         }
-        const mapped = failure.index < openingSteps ? openingStepError(failure.index, failure.error) : mapPgDriverError({ error: failure.error });
+        const mapped = queuedFailure ?? (failure.index < openingSteps ? openingStepError(failure.index, failure.error) : mapPgDriverError({ error: failure.error }));
         if (failure.index < openingSteps || outcome.transportError !== undefined && openingSteps > 0)
           openingFailure = mapped;
         if (typeof mapped.meta.sqlstate === "string")
@@ -1933,7 +1986,7 @@ function pgAdapter(options) {
           }
         });
       };
-      const sendRefusal = () => ridden !== undefined ? commitSentRefusal() : cancellationAttempted ? transactionAbortedError2({ cause: readCancelledError2({ stage: "running" }) }) : openingFailure !== undefined ? transactionAbortedError2({ cause: openingFailure }) : scope.state.poisoned ?? (scope.state.aborted === null ? undefined : transactionAbortedError2({ cause: scope.state.aborted.cause }));
+      const sendRefusal = () => queuedFailure !== undefined ? queuedFailure : ridden !== undefined ? commitSentRefusal() : cancellationAttempted ? transactionAbortedError2({ cause: readCancelledError2({ stage: "running" }) }) : openingFailure !== undefined ? transactionAbortedError2({ cause: openingFailure }) : scope.state.poisoned ?? (scope.state.aborted === null ? undefined : transactionAbortedError2({ cause: scope.state.aborted.cause }));
       const ridesQueued = (live) => {
         const last = live.at(-1);
         if (last === undefined || last.commit !== true && last.lane.seat?.group.final !== true || queued.length > 0 || inFlight !== null || ordinaryOpen > 0 || !ridesNow())
@@ -1976,18 +2029,24 @@ 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) => 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 sendBatch = () => {
+          for (const step of control)
+            step.onStart?.();
+          return 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);
         if (rides)
           trackRidden(batch, commitIndex);
         const burst = batch.then((received) => {
-          distributeBurst({ outcome: rides ? beforeCommit({ outcome: received, commitIndex }) : received, live, controlSteps: control.length, openingSteps });
+          const outcome = rides ? beforeCommit({ outcome: received, commitIndex }) : received;
+          observeDeferred(control, outcome);
+          distributeBurst({ outcome, live, controlSteps: control.length, openingSteps });
         }).then(undefined, (error) => {
           if (openingSteps > 0)
             openingFailure ??= mapPgDriverError({ error });
@@ -2516,7 +2575,7 @@ function pgAdapter(options) {
           throw riding.state === "skipped" ? transactionAbortedError2({ cause: scope.state.aborted?.cause }) : riding.error;
         }
         budget.assertUsable({ stage: "commit" });
-        if (!deferred.opened()) {
+        if (!deferred.opened() && !deferred.hasRequired()) {
           budget.close({ outcome: "committed" });
           return result;
         }
@@ -2559,7 +2618,7 @@ function pgAdapter(options) {
           budget.close({ outcome: "committed" });
           throw caught;
         }
-        const error = riding?.state === "lost" ? riding.error : caught;
+        const error = riding?.state === "lost" ? riding.error : queuedFailure ?? caught;
         if (isSavepointRollbackFailedError(error) || scope.state.poisoned !== null) {
           discard = true;
           budget.close({ outcome: "unknown" });
@@ -2715,4 +2774,4 @@ export {
   validateTransactionDeadline2 as validateTransactionDeadline
 };
 
-//# debugId=7B0EC2D2FB69EE3264756E2164756E21
+//# debugId=F571608C9B212DA864756E2164756E21