@voltro/sql-postgres 0.32.0 → 0.34.0

package/dist/index.d.ts

@@ -20,6 +20,29 @@ import { SqlDialect } from '@voltro/database';
 import { SqlError } from '@effect/sql';
 import { TransactionConnection } from '@effect/sql/SqlClient';
 
+/**
+ * Every number the CDC consumer would otherwise pick on your behalf, with its
+ * default. Each is also readable from the environment, so an operator can tune
+ * a running deployment without a code change.
+ */
+declare interface CdcRehydrateTunables {
+    /**
+     * Total budget for recovering ONE oversized change, retries included. The
+     * LISTEN consumer is serial, so this is also the longest a single oversized
+     * row can hold up the change stream. Past it the event is delivered
+     * image-less and counted `unrecovered`.
+     * Default `5_000`ms. Env: `VOLTRO_CDC_REHYDRATE_TIMEOUT_MS`.
+     */
+    readonly rehydrateTimeoutMs: number;
+    /**
+     * Re-reads AFTER the first attempt, inside the budget above (50 ms, doubling).
+     * A transient read failure is the one part of this that IS retryable — the
+     * loss it prevents is not.
+     * Default `2`. `0` disables retry. Env: `VOLTRO_CDC_REHYDRATE_RETRIES`.
+     */
+    readonly rehydrateRetries: number;
+}
+
 /**
  * Parse a `ConnectionConfig` from the cross-dialect interface into the
  * postgres-specific `PostgresConnection` shape.
@@ -108,6 +131,23 @@ export declare interface PostgresConnection {
      * `maxConnections`, the process is `maxConnections + 1`, and a budget built
      * on the first number is short by exactly one per pod — which surfaces as the
      * LAST pod of a rollout failing to connect, not as a pool warning.
+     *
+     * **`+1` is this process. It is NOT the deployment's number**, and writing it
+     * here as if it were is what made the same consumer measure THREE standalone
+     * connections against a docstring promising one. The web process
+     * (`voltro start`) opens up to two of its own, and one of them is not a
+     * `LISTEN` at all — so "count the LISTENs" undercounts:
+     *
+     *   - api  `serve` — the CDC LISTEN consumer above          (+1)
+     *   - web  `start` — the ISR invalidator's LISTEN, when any page declares
+     *                    `cacheInvalidatesOn`                    (+1)
+     *   - web  `start` — the postgres ISR cache client, under
+     *                    `SSR_CACHE=postgres`                     (+1)
+     *
+     * Do not turn that into a bigger constant. The count is per PROCESS and only
+     * the process knows what it armed, which is why `formatDbPoolLine` takes the
+     * list and prints it at boot instead of this docstring naming a number an
+     * operator then has to trust.
      */
     readonly maxConnections?: number;
     /** TLS. `true` = `sslmode=require` semantics (encrypt, skip certificate
@@ -144,6 +184,14 @@ export declare interface PostgresConnection {
      * the pool would have freed up eventually: it names the pool as the cause, at
      * the moment it is the cause, instead of surfacing as an unexplained latency
      * spike in a place with no connection information in it.
+     *
+     * **It shipped bounded on ONE of the two layer paths**, which is the part
+     * worth remembering. The bound sat inside the hand-built `pg.Pool` branch —
+     * reached only when `DB_SCHEMA` or `DB_STATEMENT_TIMEOUT_MS` is set — while
+     * the default configuration went through `PgClient.layerConfig` with no
+     * `connectTimeout` at all. The fix is not "add a timeout", it is that BOTH
+     * paths now read one resolver (`resolveAcquireTimeoutMs`); a per-branch copy
+     * of a default is how the first one drifted.
      */
     readonly acquireTimeoutMs?: number;
 }
@@ -153,13 +201,33 @@ export declare class PostgresDataStore implements DataStore {
     private readonly runtime;
     private readonly changeStrategy;
     private readonly cdcChannel;
+    private readonly cdcRehydrate;
     private readonly emitter;
     private cdcFiber;
     /** In-flight count of `transactional()` calls. `close()` waits for
      *  this to drop to 0 (or its grace period to expire) before disposing
      *  the runtime — preventing connection-pool teardown mid-COMMIT. */
     private inflightTxns;
-    constructor(sql: SqlClient.SqlClient, runtime: ManagedRuntime.ManagedRuntime<SqlClient.SqlClient | PgClient.PgClient, never>, changeStrategy: ChangeStrategy, cdcChannel: string);
+    /** Reports the first oversized change per table + every unrecovered one.
+     *  Instance-scoped so the once-per-table rate limit is the STORE's, not a
+     *  module global that a second store in one process would silence. */
+    private readonly reportOversized;
+    /** PERF-23 — counts EVERY eager JSON-agg → walker degradation and logs a
+     *  rate-limited line. Instance-scoped for the same reason as above. */
+    private readonly reportEagerFallback;
+    constructor(sql: SqlClient.SqlClient, runtime: ManagedRuntime.ManagedRuntime<SqlClient.SqlClient | PgClient.PgClient, never>, changeStrategy: ChangeStrategy, cdcChannel: string, cdcRehydrate?: CdcRehydrateTunables);
+    /**
+     * The DIALECT half of the shared transaction bracket
+     * (`runStoreTransaction` / `runRetryingTransaction` in `@voltro/database`).
+     *
+     * Postgres owns exactly four things here: its client's `withTransaction`, its
+     * managed runtime, its retryable-failure predicate and the span labels.
+     * Attribution threading, retry, commit-defect promotion and exit settling are
+     * NOT here on purpose — every one of them had already drifted between the four
+     * dialect stores, and `transactional()` and `runInNamespace()` had drifted
+     * from each other inside this very file. See `transactionOutcome.ts`.
+     */
+    private txnSpec;
     /**
      * Bind a per-request tenant NAMESPACE (a postgres SCHEMA). The returned
      * view runs every operation inside a transaction whose first statement
@@ -195,6 +263,14 @@ export declare class PostgresDataStore implements DataStore {
      * fully isolated. The public methods pass `null/null`; the view passes
      * its own captured TxnContext + per-call events buffer.
      */
+    /**
+     * Run one SELECT.
+     *
+     * `namespace` is the physical-tenant schema when the read took the
+     * transaction-free fast path (see `PostgresNamespaceView.query`); `null` on
+     * every other path, including inside a `SET LOCAL search_path` transaction,
+     * where qualifying as well would be redundant.
+     */
     private executeQuery;
     private executeInsert;
     private executeUpdate;
@@ -239,13 +315,18 @@ export declare class PostgresDataStore implements DataStore {
      * The fallback-on-throw catches dialect quirks I couldn't predict
      * up front — anything that breaks the JSON-agg query (driver
      * compatibility, schema feature) silently degrades to walker
-     * instead of surfacing a routing-level error. The log line on
-     * fallback makes the degradation visible during dev.
+     * instead of surfacing a routing-level error.
+     *
+     * PERF-23 — the degradation is COUNTED, not just logged. A log line makes it
+     * visible to whoever is watching the terminal; `voltro_db_eager_fallback_total`
+     * makes it visible to whoever looks in three weeks, which is when a
+     * per-query cliff that has been running the whole time actually gets noticed.
      */
     private runWithEager;
     /** Friend accessor for the transactional view — same eager-aware
      *  path as the public `query()` but pinned to the view's txn. */
     getInternalRunWithEager(): (d: QueryDescriptor, txn: TxnContext | null) => Promise<ReadonlyArray<Row>>;
+    /* Excluded from this release type: queryInNamespace */
     /**
      * Bracket a NON-transactional write: capture the request identity before the
      * first await (`withCapturedAttribution`), and hold this table's transport
@@ -332,16 +413,19 @@ export declare class PostgresDataStore implements DataStore {
      *   4. ChangeEvents queue in the view's buffer; on commit they drain
      *      to the parent's emitter. On throw they're dropped.
      *
-     * Resilience:
+     * Resilience (all of it owned by the shared bracket, not by this file):
      *   - Automatic retry on `serialization_failure` (40001) and
      *     `deadlock_detected` (40P01) with exponential backoff (10ms base,
-     *     up to 3 attempts). Each retry rebuilds a fresh view — the
+     *     up to 3 retries). Each retry rebuilds a fresh view — the
      *     aborted attempt's events were never drained, so the retry's
      *     subscribers see exactly one event-set (the winning attempt's).
-     *   - The whole `transactional()` boundary is wrapped in an
-     *     `Effect.withSpan('store.transactional')` so OpenTelemetry
-     *     collectors see one span per logical mutation, with retry counts
-     *     and committed-event counts as attributes.
+     *   - A conflict raised at COMMIT arrives as a DEFECT (`@effect/sql` runs
+     *     COMMIT as `Effect.orDie`) and is promoted back to a failure so the
+     *     schedule can see it.
+     *   - The whole boundary is one `Effect.withSpan('store.transactional')` so
+     *     OpenTelemetry collectors see one span per logical mutation.
+     *   - The Exit settles through `settleTransactionExit`, so a typed error
+     *     reaches the caller with its `_tag` rather than as a `FiberFailure`.
      */
     transactional<T>(work: (tx: DataStore) => Promise<T>): Promise<T>;
     onChange(listener: (event: ChangeEvent) => void): () => void;
@@ -374,10 +458,32 @@ export declare class PostgresDataStore implements DataStore {
     close(gracePeriodMs?: number): Promise<void>;
     /** Liveness probe — `SELECT 1`. Rejects if the pool can't answer. */
     ping(): Promise<void>;
+    /**
+     * Read one row back as the JSON the trigger could not send.
+     *
+     * `row_to_json(t)` on purpose: it is literally what `triggerFunctionSql`
+     * builds its images with, so a re-hydrated row and an ordinary CDC image are
+     * the same shape — dates as ISO strings, numerics as JSON numbers. A plain
+     * `SELECT *` would hand the driver's types to consumers that have only ever
+     * seen the JSON ones, which is a second shape to get right in every tap.
+     *
+     * SCHEMA-QUALIFIED, from the payload's own `schema`. Under namespace
+     * isolation the write landed in `tenant_<id>`, and an unqualified read
+     * resolves through this connection's `search_path` instead — which is another
+     * tenant's table of the same name, or none.
+     */
+    private readRowAsCdcJson;
     /**
      * Subscribe to the Postgres NOTIFY channel and translate each notification
      * into a ChangeEvent. Called automatically from `makePostgresDataStore`
      * when `changeStrategy: 'cdc'`.
+     *
+     * An OVERSIZED notification is re-hydrated HERE, before anything downstream
+     * sees it. This is the one place every consumer is downstream of — the
+     * dispatcher, the plugin taps, the analytics mirror, the DevTools CDC
+     * producer and the ISR invalidator all hang off the emitter this feeds — so
+     * it is the only place the repair can be made once. See `cdcRehydrate.ts` for
+     * what re-hydration can and cannot recover.
      */
     startCdcConsumer(): Promise<void>;
 }
@@ -401,6 +507,14 @@ export declare interface PostgresDataStoreOptions {
     readonly changeStrategy?: ChangeStrategy;
     /** Postgres NOTIFY channel name when changeStrategy is 'cdc'. Defaults to 'framework_changes'. */
     readonly cdcChannel?: string;
+    /** Budget for re-reading ONE row whose change exceeded the NOTIFY payload cap
+     *  — see {@link CdcRehydrateTunables.rehydrateTimeoutMs}. Defaults to 5000ms
+     *  (env `VOLTRO_CDC_REHYDRATE_TIMEOUT_MS`). */
+    readonly cdcRehydrateTimeoutMs?: number;
+    /** Re-reads after the first attempt, inside that budget — see
+     *  {@link CdcRehydrateTunables.rehydrateRetries}. Defaults to 2
+     *  (env `VOLTRO_CDC_REHYDRATE_RETRIES`). */
+    readonly cdcRehydrateRetries?: number;
 }
 
 /**