@voltro/sql-mssql 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -62,9 +62,11 @@ export declare interface ChangeTrackingCdcOptions {
  *   2. Discrete `host`/`port`/`username`/`password`/`database`
  *   3. Defaults: server `localhost`, port 1433
  *
- * Sane defaults for dev: `trustServer: true` so the docker SQL Server
- * Developer edition's self-signed cert doesn't trip TLS. Production
- * setups override via env.
+ * TLS: an explicit `config.ssl` wins; otherwise the URL query decides (see
+ * `sslFromUrlQuery`); otherwise unset — plaintext, the driver's default.
+ * `ssl: true` becomes `encrypt: true` + `trustServer: true`, which is what
+ * `sslmode=require` means on tedious and is what lets the docker SQL Server
+ * Developer edition's self-signed certificate work.
  */
 export declare const connectionFromConfig: (config: ConnectionConfig) => MssqlConnection;
 
@@ -94,9 +96,39 @@ export declare interface MssqlConnection {
     readonly database?: string;
     readonly username?: string;
     readonly password?: string;
+    /**
+     * TLS on the wire (tedious `encrypt`). Unset = `@effect/sql-mssql`'s own
+     * default, which is **`false`** — it overrides tedious' `true`
+     * (`MssqlClient.js:54`), so an mssql connection is plaintext unless something
+     * asks otherwise.
+     *
+     * That "something" used to be nothing: `connectionFromConfig` never read
+     * `ConnectionConfig.ssl`, so `DB_URL=mssql://…?ssl=true` or `PG_SSL=require`
+     * connected in plaintext — the same silent downgrade the mysql dialect had.
+     * It is derived from `ssl` now, and an unsupported request throws.
+     */
     readonly encrypt?: boolean;
+    /**
+     * Skip verification of the server certificate (tedious
+     * `trustServerCertificate`). Only meaningful with `encrypt: true`, where it
+     * is what makes `sslmode=require` semantics — encrypt, don't authenticate the
+     * server — expressible on this driver.
+     */
     readonly trustServer?: boolean;
     readonly maxConnections?: number;
+    /**
+     * Bound on ESTABLISHING a connection (ms) — `@effect/sql-mssql`'s
+     * `connectTimeout`, which is tedious' connect timeout AND the deadline on the
+     * boot `SELECT 1` probe (`MssqlClient.js:230`). Default
+     * {@link DEFAULT_ACQUIRE_TIMEOUT_MS}, `0` = the driver's own (5 s probe).
+     *
+     * As on mysql, this does NOT bound waiting for a BUSY pooled connection:
+     * `@effect/sql-mssql` pools through an Effect `Pool` whose `get` takes no
+     * timeout, and the client exposes no knob for it. Naming that gap is the
+     * point — the same reason `statementTimeoutMs` is left unwired here rather
+     * than mapped onto `connectTimeout`, which bounds a different phase.
+     */
+    readonly acquireTimeoutMs?: number;
 }
 
 export declare const mssqlDialect: SqlDialect;
@@ -117,6 +149,10 @@ export declare class MssqlStore implements DataStore {
     private readonly namespace;
     private readonly emitter;
     private inflightTxns;
+    /** PERF-23 — counts EVERY eager JSON-agg → walker degradation and logs a
+     *  rate-limited line. Instance-scoped so a second store in one process cannot
+     *  silence this one's first warning. */
+    private readonly reportEagerFallback;
     private cdcHandle;
     private cdcCheckpointTimer;
     private cdcPendingVersion;
@@ -174,6 +210,18 @@ export declare class MssqlStore implements DataStore {
     }): Promise<ReadonlyArray<T>>;
     private runWithEager;
     /* Excluded from this release type: getInternalRunWithEager */
+    /**
+     * Bracket a NON-transactional write: the attribution capture every public
+     * write already did, plus the ONE metrics funnel for this dialect's writes
+     * (`voltro_db_queries_total{op}`).
+     *
+     * Named to match postgres' / mysql's `localWrite`. Those two additionally
+     * hold the table's transport echoes for the write's duration; Change Tracking
+     * has no per-write NOTIFY echo to order against, so this one is the
+     * attribution + metrics half only. One name for the write funnel across four
+     * stores is what lets the parity test ask the question at all.
+     */
+    private localWrite;
     insert(t: string, r: Row): Promise<Readonly<Record<string, unknown>>>;
     insertMany(t: string, rows: ReadonlyArray<Row>): Promise<readonly Readonly<Record<string, unknown>>[]>;
     patchJson(t: string, pk: string, path: string, value: unknown): Promise<Readonly<Record<string, unknown>> | null>;
@@ -223,6 +271,16 @@ export declare class MssqlStore implements DataStore {
     /* Excluded from this release type: getInternalExecuteUpsert */
     /* Excluded from this release type: getInternalExecuteInsertIgnore */
     transactional<T>(work: (tx: DataStore) => Promise<T>): Promise<T>;
+    /**
+     * The DIALECT half of the shared transaction bracket
+     * (`runStoreTransaction` in `@voltro/database`).
+     *
+     * mssql owns three things: the client's `withTransaction`, the runtime, and
+     * `isRetryableMssqlFailure` (deadlock victim, 1205). Retry, commit-defect
+     * promotion, attribution threading and exit settling are shared — see
+     * `transactionOutcome.ts` for why none of those may be re-decided here.
+     */
+    private txnSpec;
     onChange(listener: (event: ChangeEvent) => void): () => void;
     /** 'fleet' under Change Tracking CDC (every replica gets the full
      *  stream); 'local' under inline emission. See DataStore.changeScope. */