@voltro/sql-mysql 0.32.0 → 0.34.0

package/dist/index.d.ts

@@ -143,6 +143,10 @@ declare class CdcDeliveryGate {
  * and the dialect's `id` field is what discriminates downstream.
  *
  * Defaults: port 3306, user `app`, password `app`, database `app`.
+ *
+ * TLS: an explicit `config.ssl` wins; otherwise the URL's `?sslmode=` / `?ssl=`
+ * query decides (see `sslFromUrlQuery`); otherwise unset — plaintext, mysql2's
+ * default.
  */
 export declare const connectionFromConfig: (config: ConnectionConfig) => MysqlConnection;
 
@@ -180,6 +184,53 @@ export declare interface MysqlConnection {
     readonly password: string;
     readonly database: string;
     readonly maxConnections?: number;
+    /**
+     * TLS. `true` = encrypt without certificate verification (`sslmode=require`
+     * semantics, matching the postgres dialect and the cross-dialect
+     * `ConnectionConfig.ssl`); `false`/unset = plaintext, mysql2's default.
+     *
+     * **There was no TLS path here at all.** `MysqlConnection` carried no `ssl`
+     * field, `connectionFromConfig` read neither `config.ssl` nor the URL query,
+     * and `makeMysqlSqlLayer` passed the driver nothing — so
+     * `DB_URL=mysql://…?ssl=true` connected in PLAINTEXT with no warning and no
+     * error. A TLS request that cannot be honoured now throws
+     * (see `sslFromUrlQuery`); it never silently downgrades.
+     */
+    readonly ssl?: boolean;
+    /**
+     * Bound on ESTABLISHING a connection (ms) — mysql2's `connectTimeout`.
+     * Default {@link DEFAULT_ACQUIRE_TIMEOUT_MS}, `0` = the driver's own.
+     *
+     * Note precisely what this does NOT cover, because the name promises more on
+     * postgres than mysql2 can deliver: mysql2's pool has **no time-based bound
+     * on waiting for a busy connection**. `lib/base/pool.js` pushes the waiting
+     * callback onto `_connectionQueue` and there is no timer anywhere near it, so
+     * the queued half is UNBOUNDED — {@link acquireQueueLimit} is the only bound
+     * available and is opt-in. Mapping this value onto the wait would be
+     * inventing a guarantee.
+     *
+     * At the framework default this is a no-op: mysql2 already defaults
+     * `connectTimeout` to 10 s (`lib/connection_config.js:115`). It is passed
+     * anyway so the value is ONE decision across dialects and an operator who
+     * lowers it gets it honoured here too — not so that mysql suddenly gains a
+     * bound it had.
+     */
+    readonly acquireTimeoutMs?: number;
+    /**
+     * How many callers may be queued waiting for a free pooled connection before
+     * the next one fails immediately — mysql2's `queueLimit`. **Unset by
+     * default**, i.e. mysql2's own unbounded queue; `0` spells the same thing.
+     *
+     * Opt-in rather than defaulted, and the reason is a measured wedge rather
+     * than caution: past the limit mysql2 rejects the acquire SYNCHRONOUSLY (its
+     * queue-limit branch is the one error return in `getConnection` that skips
+     * `process.nextTick`), so any caller that retries an acquire failure without
+     * a delay spins in-tick forever and the event loop — hence every timer, and
+     * hence the drain that would clear the queue — is never reached again.
+     * `@effect/cluster`'s per-shard release does exactly that. Full account on
+     * `ConnectionConfig.acquireQueueLimit`.
+     */
+    readonly acquireQueueLimit?: number;
 }
 
 /**
@@ -208,6 +259,10 @@ export declare class MysqlStore implements DataStore {
     private cdcReplicaId;
     private cdcStreamName;
     private readonly cdcGate;
+    /** 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;
     constructor(sql: SqlClient.SqlClient, runtime: ManagedRuntime.ManagedRuntime<SqlClient.SqlClient | MysqlClient.MysqlClient, never>, variant: 'mysql' | 'mariadb', changeStrategy?: ChangeStrategy, namespace?: QueryNamespace, sharedEmitter?: EventEmitter, sharedGate?: CdcDeliveryGate);
     /**
      * Bind a per-request tenant namespace (a DATABASE on mysql/mariadb),
@@ -284,6 +339,13 @@ export declare class MysqlStore implements DataStore {
      * the range is [first, first + n - 1]. Re-selects that range ordered by
      * id (= input order) for the post-images. Same connection-pinning +
      * retry as the single-row path.
+     *
+     * Takes the rows ALREADY CHUNKED (`bulkInsertLimits.ts`) and walks the chunks
+     * on the one pinned connection, because the contiguous-range guarantee is per
+     * STATEMENT: each chunk has its own `LAST_INSERT_ID()` and its own
+     * `[first, first + chunkLen - 1]`. Chunking outside this function — issuing
+     * the inserts and then asking once — would read one chunk's range and lose
+     * the rest, which is worse than the limit error it replaces.
      */
     private insertManyRecoverAutoIds;
     private executePatchJson;
@@ -398,6 +460,18 @@ export declare class MysqlStore 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`).
+     *
+     * mysql/mariadb own three things: the client's `withTransaction`, the runtime,
+     * and `isRetryableMysqlFailure` (deadlock / lock-wait timeout). Retry,
+     * commit-defect promotion, attribution threading and exit settling are shared
+     * — this store carried its own copy of the last one for a release after
+     * postgres was fixed, and a consumer on MariaDB paid for it. See
+     * `transactionOutcome.ts`.
+     */
+    private txnSpec;
     onChange(listener: (event: ChangeEvent) => void): () => void;
     /** Cross-instance reactivity seam — emit an externally-sourced event to
      *  local subscribers without re-persisting. The binlog CDC consumer and