@voltro/sql-postgres 0.33.0 → 0.35.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.
@@ -43,6 +66,27 @@ export declare type DatabaseConnectionLayer = ReturnType<typeof makePostgresSqlL
 
 export declare type DatabaseConnectionLayerInput = Parameters<typeof makePostgresSqlLayer>[0];
 
+/** Encode one row as a COPY TEXT line (no trailing newline). */
+export declare const encodeCopyRow: (row: Readonly<Record<string, unknown>>, columns: ReadonlyArray<string>, columnTypes?: Readonly<Record<string, string>>) => string;
+
+/**
+ * Encode one field value to its LOGICAL text (before COPY escaping).
+ * `null` means SQL NULL (`\N` on the wire).
+ *
+ * `columnType` is the bundle's logical type for the column, used only where
+ * the JS value alone is ambiguous: a JS array under a `json` column is JSON
+ * text, under an `array` column a pg array literal, under a `vector` column
+ * the pgvector `[…]` form.
+ */
+export declare const encodeCopyValue: (value: unknown, columnType: string | undefined) => string | null;
+
+/**
+ * Open a COPY session on its OWN connection (the same posture as the native
+ * `pg_dump`/`pg_restore` runners — bulk load does not ride the app pool).
+ * The connection opens lazily on the first `copyInto`.
+ */
+export declare const makePgCopySession: (config: ConnectionConfig) => PgCopySession;
+
 /**
  * Construct a `PostgresDataStore`. The owned `ManagedRuntime` keeps the
  * connection pool alive for the lifetime of the store; `close()` disposes it.
@@ -76,6 +120,25 @@ export declare const makePostgresSqlLayerFromConfig: (config: ConnectionConfig)
 
 export { PgClient }
 
+export declare interface PgCopyBatch {
+    readonly table: string;
+    readonly columns: ReadonlyArray<string>;
+    /** Bundle logical column types (json/array/vector/…), for the values the JS
+     *  type alone cannot disambiguate. */
+    readonly columnTypes?: Readonly<Record<string, string>>;
+    readonly rows: ReadonlyArray<Record<string, unknown>>;
+}
+
+export declare interface PgCopySession {
+    /** The dialect this loader serves — the importer's eligibility key. */
+    readonly dialect: 'postgres';
+    /** COPY one batch into `table`. Resolves the server-reported row count.
+     *  Atomic per call: a failure applied NOTHING (single statement). */
+    readonly copyInto: (batch: PgCopyBatch) => Promise<number>;
+    /** Close the dedicated connection. Idempotent. */
+    readonly close: () => Promise<void>;
+}
+
 /**
  * Internal handle a `PostgresDataStore` exposes so this adapter can
  * issue raw SQL against the same managed runtime + connection pool.
@@ -161,6 +224,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;
 }
@@ -170,13 +241,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
@@ -212,6 +303,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;
@@ -256,13 +355,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
@@ -349,16 +453,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;
@@ -391,10 +498,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>;
 }
@@ -418,6 +547,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;
 }
 
 /**