@voltro/sql-postgres 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,375 @@
+import { ChangeEvent } from '@voltro/database';
+import { ChangeStrategy } from '@voltro/database';
+import { ConfigError } from 'effect';
+import { ConnectionConfig } from '@voltro/database';
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { DialectReplicationAdapter } from '@voltro/database';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { ManagedRuntime } from 'effect';
+import { PgClient } from '@effect/sql-pg';
+import { Predicate } from '@voltro/database';
+import { QueryDescriptor } from '@voltro/database';
+import { RawSqlFragment } from '@voltro/database/sql';
+import { RetryDecision } from '@voltro/database';
+import { Row } from '@voltro/database';
+import { SqlClient } from '@effect/sql';
+import { SqlClient as SqlClient_2 } from '@effect/sql/SqlClient';
+import { SqlDialect } from '@voltro/database';
+import { SqlError } from '@effect/sql';
+import { TransactionConnection } from '@effect/sql/SqlClient';
+
+/**
+ * Parse a `ConnectionConfig` from the cross-dialect interface into the
+ * postgres-specific `PostgresConnection` shape.
+ *
+ * Resolution order:
+ *   1. If `url` is present, parse it (`postgres://user:pw@host:port/db`).
+ *   2. Otherwise use discrete fields.
+ *   3. Anything missing falls back to canonical defaults
+ *      (localhost / 5432 / app / app / app) so dev-mode `voltro dev`
+ *      without env config still boots against a default-config postgres.
+ *
+ * TLS: an explicit `config.ssl` wins; otherwise the URL's `?sslmode=` /
+ * `?ssl=` query decides (see `sslFromUrlQuery`); otherwise unset — the
+ * driver default. `ssl: true` maps to `sslmode=require` semantics,
+ * `ssl: false` forces plaintext (see `sslDriverOption` for the exact
+ * driver options).
+ */
+export declare const connectionFromConfig: (config: ConnectionConfig) => PostgresConnection;
+
+export declare type DatabaseConnectionLayer = ReturnType<typeof makePostgresSqlLayer>;
+
+export declare type DatabaseConnectionLayerInput = Parameters<typeof makePostgresSqlLayer>[0];
+
+/**
+ * Construct a `PostgresDataStore`. The owned `ManagedRuntime` keeps the
+ * connection pool alive for the lifetime of the store; `close()` disposes it.
+ */
+export declare const makePostgresDataStore: (options: PostgresDataStoreOptions) => Promise<PostgresDataStore>;
+
+/**
+ * Build a `PgClient` Layer from explicit field values.
+ *
+ * Marked exported because the CLI's migrate / dbCommand still construct
+ * the layer directly from environment values; once those callsites move
+ * to the dialect resolver they'll go through `postgresDialect.makeSqlLayer`
+ * and this becomes an internal helper.
+ *
+ * When `schema` is set, every pooled connection opens with
+ * `search_path = <schema>` (the PG `options` startup parameter, applied by
+ * the server BEFORE any query — no pool-rotation race), so introspection
+ * (`current_schema()`), unqualified DDL, and runtime queries all target it.
+ * `@effect/sql-pg`'s config can't carry that param, so we hand it a
+ * pre-built `pg.Pool` via `layerFromPool`. No schema → the unchanged
+ * `layerConfig` path (zero behaviour change).
+ */
+export declare const makePostgresSqlLayer: (options: PostgresConnection) => ReturnType<typeof PgClient.layerConfig>;
+
+/**
+ * The cross-dialect `SqlDialect.makeSqlLayer` implementation for postgres.
+ * Takes a generic `ConnectionConfig`, parses it via `connectionFromConfig`,
+ * and produces the same PgClient Layer that direct callers would build.
+ */
+export declare const makePostgresSqlLayerFromConfig: (config: ConnectionConfig) => ReturnType<typeof PgClient.layerConfig>;
+
+export { PgClient }
+
+/**
+ * Internal handle a `PostgresDataStore` exposes so this adapter can
+ * issue raw SQL against the same managed runtime + connection pool.
+ *
+ * The framework's `ReplicatedDataStore` typing only sees a generic
+ * `DataStore`, so this adapter casts at the call site after checking
+ * for the friend-handle's presence — same pattern the dispatcher
+ * uses for transactional view internals.
+ */
+declare interface PostgresAdapterFriend {
+    readonly runEffect: <A, E>(effect: Effect.Effect<A, E, SqlClient_2>) => Promise<A>;
+}
+
+export declare interface PostgresConnection {
+    readonly host: string;
+    readonly port: number;
+    readonly username: string;
+    readonly password: string;
+    readonly database: string;
+    /** Connection-pool size; defaults to 10. */
+    readonly maxConnections?: number;
+    /** TLS. `true` = `sslmode=require` semantics (encrypt, skip certificate
+     *  verification — see `sslDriverOption`); `false` = force plaintext (also
+     *  overrides a `PGSSLMODE` the driver would otherwise pick up from the
+     *  process env); unset = the driver default (plaintext unless `PGSSLMODE`
+     *  says otherwise). */
+    readonly ssl?: boolean;
+    /** Pin the connection `search_path` to this schema (env `DB_SCHEMA`).
+     *  See `ConnectionConfig.schema`. */
+    readonly schema?: string;
+}
+
+export declare class PostgresDataStore implements DataStore {
+    private readonly sql;
+    private readonly runtime;
+    private readonly changeStrategy;
+    private readonly cdcChannel;
+    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);
+    /**
+     * Bind a per-request tenant NAMESPACE (a postgres SCHEMA). The returned
+     * view runs every operation inside a transaction whose first statement
+     * is `SET LOCAL search_path TO "<namespace>"`, so unqualified table
+     * names resolve to that tenant's schema — and the setting RESETS at
+     * commit/rollback. This is mandatory on a pooled connection: a bare
+     * `SET search_path` would persist on the connection and leak into the
+     * NEXT request that checks the same connection out of the pool. `SET
+     * LOCAL` is transaction-scoped, so the leak window is closed.
+     *
+     * `null` returns `this` — the shared-schema default (no search_path
+     * manipulation).
+     */
+    withNamespace(namespace: string | null): DataStore;
+    /* Excluded from this release type: runInNamespace */
+    /**
+     * Friend-handle the postgres replication adapter reads via a
+     * structural check on `DataStore` (declared in `./replicationAdapter.ts`).
+     * The adapter needs raw SQL access against THIS store's managed
+     * runtime to issue `pg_current_wal_lsn()` / `pg_last_wal_replay_lsn()`
+     * — without a friend handle it would need its own connection pool +
+     * config, which would double the deployment cost.
+     *
+     * The handle stays on the store class as a public-but-prefixed
+     * property so the type cast in `adapterFriend(store)` resolves
+     * without exporting the runtime to the wider API surface.
+     */
+    readonly __postgresReplicationFriend: PostgresAdapterFriend;
+    /**
+     * Core write/read path. Both the public-store API (no txn) and the
+     * per-transactional-view (with txn) flow through these, with explicit
+     * txn-context + event-sink params so concurrent transactions remain
+     * fully isolated. The public methods pass `null/null`; the view passes
+     * its own captured TxnContext + per-call events buffer.
+     */
+    private executeQuery;
+    private executeInsert;
+    private executeUpdate;
+    private executeUpsert;
+    private executeInsertIgnore;
+    private executeInsertMany;
+    private executePatchJson;
+    private executeDelete;
+    /** Inside a transaction → push into the per-call events buffer (drained
+     *  on commit, dropped on throw); outside → emit live. */
+    private routeEvent;
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
+    raw<T extends object = Row>(fragment: RawSqlFragment, _opts?: {
+        dependsOn?: ReadonlyArray<string>;
+    }): Promise<ReadonlyArray<T>>;
+    /**
+     * Run a query, applying eager-loads when present.
+     *
+     * Path A (fast): compile to ONE roundtrip via `compileEagerJson` →
+     * postgres' `to_jsonb(parent.*) || jsonb_build_object('rel', ...)`
+     * shape. Each parent comes back with relations already nested as
+     * jsonb. Decoder restores Date types per schema.
+     *
+     * Path B (walker fallback): when compilation returns null
+     * (registry miss, unsupported feature, etc.) OR the JSON-agg
+     * execution throws, run the base SELECT + the portable walker.
+     * Walker is the canonical correctness path; JSON-agg is the perf
+     * layer.
+     *
+     * 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.
+     */
+    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>>;
+    insert(table: string, row: Row): Promise<Row>;
+    insertMany(table: string, rows: ReadonlyArray<Row>): Promise<ReadonlyArray<Row>>;
+    patchJson(table: string, primaryKey: string, path: string, value: unknown): Promise<Row | null>;
+    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row | null>;
+    delete(table: string, primaryKey: string): Promise<boolean>;
+    updateMany(table: string, patch: Readonly<Record<string, unknown>>, options: {
+        where: Predicate;
+    }): Promise<number>;
+    deleteMany(table: string, options: {
+        where: Predicate;
+    }): Promise<number>;
+    /**
+     * Q9 v2 — single-statement `UPDATE ... WHERE <pred> RETURNING *`.
+     * Postgres supports RETURNING on UPDATE; we use it to fan out the
+     * per-row ChangeEvent reactive subscribers expect, without paying the
+     * SELECT-then-update round-trip cost. The predicate lives on the write
+     * itself, so the match is a CAS: a row that stopped matching between a
+     * caller's read and this write is never patched. When an ambient `txn`
+     * is present (the transactional view) the statement routes to that
+     * captured connection so the CAS holds inside the transaction too —
+     * this is why the view forwards here instead of SELECT-ids-then-apply-
+     * by-id, which under READ COMMITTED could patch a row that no longer
+     * matches.
+     */
+    private executeUpdateMany;
+    /**
+     * Single-statement `DELETE ... WHERE <pred> RETURNING *` — the set-based
+     * mirror of {@link executeUpdateMany}. The returned rows ARE the
+     * old-images we fan out as per-row delete ChangeEvents. Same
+     * predicate-CAS + ambient-txn routing rationale as updateMany.
+     */
+    private executeDeleteMany;
+    upsert(table: string, row: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
+    }): Promise<Row>;
+    insertIgnore(table: string, row: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+    }): Promise<Row>;
+    /* Excluded from this release type: emitChange */
+    /* Excluded from this release type: getInternalExecuteQuery */
+    /* Excluded from this release type: getInternalExecuteInsert */
+    /* Excluded from this release type: getInternalExecuteInsertMany */
+    /* Excluded from this release type: getInternalExecutePatchJson */
+    /* Excluded from this release type: getInternalExecuteUpdate */
+    /* Excluded from this release type: getInternalExecuteDelete */
+    /* Excluded from this release type: getInternalExecuteUpdateMany */
+    /* Excluded from this release type: getInternalExecuteDeleteMany */
+    /* Excluded from this release type: getInternalExecuteUpsert */
+    /* Excluded from this release type: getInternalExecuteInsertIgnore */
+    /**
+     * Run `work` inside a real Postgres transaction.
+     *
+     * Each call to `transactional()` is fully independent — two concurrent
+     * invocations run on TWO separate Connections from the pool, BEGIN/
+     * COMMIT/ROLLBACK on their own connections, see their own (uncommitted)
+     * writes via the per-call view passed to `work`, and don't conflict.
+     *
+     * Mechanism:
+     *   1. `sql.withTransaction(effect)` checks out a Connection from the
+     *      pool, issues `BEGIN`, and provides the `TransactionConnection`
+     *      service to `effect`. On effect success → `COMMIT` + release;
+     *      on failure → `ROLLBACK` + release.
+     *   2. Inside `effect` we capture the `TransactionConnection` tuple
+     *      and construct a `PostgresTransactionalView` that owns the
+     *      captured TxnContext + an events buffer. We pass it to `work`.
+     *   3. `work` calls `tx.insert/update/delete/query` on the view; the
+     *      view forwards to the parent's private execute* methods with
+     *      its TxnContext explicitly attached. Every statement therefore
+     *      routes to the SAME Connection as BEGIN — atomic at the DB level.
+     *   4. ChangeEvents queue in the view's buffer; on commit they drain
+     *      to the parent's emitter. On throw they're dropped.
+     *
+     * Resilience:
+     *   - 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
+     *     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.
+     */
+    transactional<T>(work: (tx: DataStore) => Promise<T>): Promise<T>;
+    onChange(listener: (event: ChangeEvent) => void): () => void;
+    /** Cross-instance reactivity seam — emit an externally-sourced event to
+     *  local subscribers without re-persisting. Both the LISTEN/NOTIFY CDC
+     *  consumer and `@voltro/plugin-broadcast` route through here. See
+     *  `DataStore.injectExternalChange`. */
+    /** 'fleet' under LISTEN/NOTIFY CDC (every replica gets the full stream);
+     *  'local' under inline emission. See DataStore.changeScope. */
+    get changeScope(): 'local' | 'fleet';
+    injectExternalChange(event: ChangeEvent): void;
+    /** Run an arbitrary Effect against the underlying SqlClient. */
+    run<A, E>(effect: Effect.Effect<A, E, SqlClient.SqlClient>): Promise<A>;
+    /**
+     * Tear down the connection pool + CDC consumer.
+     *
+     * Waits up to `gracePeriodMs` for in-flight `transactional()` calls to
+     * complete before disposing the runtime. Without this, a graceful
+     * shutdown that races a mid-COMMIT mutation could see the connection
+     * pool yanked out from under the transaction — undefined outcome (the
+     * write may or may not land, depending on whether COMMIT had been
+     * flushed to disk).
+     *
+     * Defaults to a 5-second grace period — long enough for typical
+     * mutations to finish, short enough that a shutdown isn't blocked
+     * indefinitely by a stuck transaction. After the grace period
+     * expires, logs a warning and proceeds with disposal anyway (the
+     * shutdown must complete).
+     */
+    close(gracePeriodMs?: number): Promise<void>;
+    /** Liveness probe — `SELECT 1`. Rejects if the pool can't answer. */
+    ping(): Promise<void>;
+    /**
+     * Subscribe to the Postgres NOTIFY channel and translate each notification
+     * into a ChangeEvent. Called automatically from `makePostgresDataStore`
+     * when `changeStrategy: 'cdc'`.
+     */
+    startCdcConsumer(): Promise<void>;
+}
+
+export declare interface PostgresDataStoreOptions {
+    /**
+     * Layer that provides the postgres SQL client. `makePostgresSqlLayer({...})`
+     * returns `Layer<PgClient | SqlClient, ConfigError | SqlError>`, which is
+     * exactly this shape.
+     */
+    readonly sqlLayer: Layer.Layer<SqlClient.SqlClient | PgClient.PgClient, ConfigError.ConfigError | SqlError.SqlError, never>;
+    /** Optional tracer layer (from `buildTracingLayer`). When provided, every
+     *  `Effect.withSpan` inside the store's runtime — most importantly
+     *  `transactional()` — emits real OpenTelemetry spans. Absent → spans
+     *  become no-ops. Typed `Layer<never>` because Layer's provided-services
+     *  channel is contravariant — `never` is the widest acceptor that
+     *  absorbs both `Layer.empty` and real tracer layers (which provide
+     *  OTel's Resource service). */
+    readonly tracerLayer?: Layer.Layer<never, never, never>;
+    /** Change emission strategy. Defaults to 'inline'. */
+    readonly changeStrategy?: ChangeStrategy;
+    /** Postgres NOTIFY channel name when changeStrategy is 'cdc'. Defaults to 'framework_changes'. */
+    readonly cdcChannel?: string;
+}
+
+/**
+ * The dialect singleton — what `loadDialect()` returns and what every
+ * dialect-aware caller (CLI buildStore, migrate, workflow layer)
+ * receives.
+ *
+ * `compileContains` keeps `ILIKE ... ESCAPE '\\'` semantics; the
+ * centralised `sqlCompiler` routes `contains` through the dialect, with
+ * this as the postgres-side dispatch target.
+ */
+export declare const postgresDialect: SqlDialect;
+
+/**
+ * Build a Postgres replication adapter.
+ *
+ * The store the adapter operates against MUST expose the
+ * `__postgresReplicationFriend` handle the framework's
+ * `PostgresDataStore` attaches at construction time. The adapter
+ * throws a clear error if the handle is missing — surfaces
+ * "wrong store passed" at the routing boundary instead of
+ * downstream as a SQL error.
+ */
+export declare const postgresReplicationAdapter: () => DialectReplicationAdapter;
+
+/** `SqlDialect.retryFilter` implementation for postgres. */
+export declare const postgresRetryFilter: (err: unknown) => RetryDecision;
+
+/**
+ * Captured inside `transactional()`'s `withTransaction` scope. Holds the
+ * `TransactionConnection` context tuple `[Connection, depth]` so we can
+ * explicitly provide it to each inner statement's Effect — without this,
+ * statements run on the shared pool and bypass our `BEGIN`.
+ */
+declare type TxnContext = Context.Tag.Service<typeof TransactionConnection>;
+
+export { }