@quereus/quereus 4.16.0 → 4.17.0

package/dist/src/core/database-auto-analyze.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Auto-analyze staleness bookkeeping and background statistics refresh.
+ *
+ * Tracks, per base table, how many distinct rows committed transactions have
+ * changed since statistics were last collected for that table, decides when that
+ * drift is large enough to call the table's statistics stale, and — off the write
+ * path, from a debounced timer — refreshes them by running the ordinary `ANALYZE`
+ * statement for that one table.
+ *
+ * The counts come from the transaction change log (`TransactionManager`), read
+ * post-commit while the log is still alive. That log is maintained
+ * unconditionally on every write path already, so counting costs one `Map.size`
+ * read per table per savepoint layer and nothing on the write path itself.
+ *
+ * The refresh goes through `db.exec('analyze …')` rather than reaching into the
+ * collection internals. Two things fall out of that:
+ *
+ * - `db.exec` acquires the database's execution mutex, which is what serializes
+ *   all statement execution. A refresh driven from a timer therefore queues
+ *   behind whatever is running instead of racing it. It cannot deadlock, because
+ *   it is never started from inside a statement.
+ * - There is exactly one implementation of "collect and record statistics for a
+ *   table" (`runtime/emit/analyze.ts`), including its per-table `try` that logs
+ *   and continues.
+ *
+ * A refresh cannot trigger itself: `ANALYZE` performs no DML, and it publishes
+ * its result by swapping the `TableSchema` and firing the internal catalog
+ * notifier rather than the data-change channel. Its implicit transaction commits
+ * with an empty change log, so no counter advances.
+ */
+import type { Database } from './database.js';
+/**
+ * First delay before retrying a refresh that was deferred because a transaction
+ * was open, doubling on each further retry (250, 500, 1000, 2000 ms).
+ *
+ * NOT the debounce: the debounce exists to let a burst of commits collapse, and
+ * 50 ms is far too soon to expect a statement that was in flight a moment ago to
+ * have finished. Starting an order of magnitude higher means the common case — a
+ * timer landing inside one ordinary `UPDATE` — is served by the first retry
+ * instead of burning the whole budget on wakeups that all land inside the same
+ * statement.
+ *
+ * NOTE: 250 ms is reasoning, not measurement — nothing has measured how long a
+ * statement actually holds its implicit transaction, and a memory-backed one
+ * frequently never yields to the timer queue at all (a 400-row `insert … values`
+ * ran to completion without a single `setTimeout(0)` firing), so this mostly
+ * governs store-backed workloads and explicit `BEGIN`s. If the debug log shows
+ * crossings routinely spending the whole budget, measure a real workload before
+ * raising the retry count — a longer first delay is likelier to be the fix.
+ */
+export declare const AUTO_ANALYZE_DEFER_RETRY_MS = 250;
+/**
+ * How many times one crossing may reschedule itself after being deferred. The
+ * geometric backoff above makes that about 3.75 s of total patience.
+ *
+ * Bounded on purpose: a user may park an explicit transaction open indefinitely,
+ * and an unbounded retry would then cost a wakeup per stale table forever. Once
+ * the budget is spent the crossing is dropped exactly as it was before retries
+ * existed — the counter stays over threshold and the next commit that touches the
+ * table re-arms.
+ *
+ * Must stay at or below `AUTO_ANALYZE_IDLE_MAX_PASSES - 2`: {@link
+ * AutoAnalyzeManager.whenIdle} spends one settle pass per retry plus one for the
+ * initial attempt and one to observe that nothing is left armed.
+ */
+export declare const AUTO_ANALYZE_MAX_DEFER_RETRIES = 4;
+/**
+ * Safety bound on {@link AutoAnalyzeManager.whenIdle}'s settle loop. Exported so the
+ * inequality against {@link AUTO_ANALYZE_MAX_DEFER_RETRIES} is checked by a test
+ * rather than only implied by one failing if it were ever violated.
+ */
+export declare const AUTO_ANALYZE_IDLE_MAX_PASSES = 10;
+/**
+ * Why a scheduled refresh ended. Only `deferred` wants a retry — it is the one
+ * outcome where nothing about the table changed and the refusal was purely about
+ * *when* the timer happened to land.
+ *
+ * The union exists so that `declined` (a deliberate refusal — feature off, table
+ * oversize, table gone) and `deferred` (transient) cannot be spelled the same way.
+ * Before it, every early return in {@link AutoAnalyzeManager['refresh']} was a bare
+ * `return` and a transient refusal silently abandoned its crossing.
+ */
+export type RefreshOutcome = 'analyzed' | 'declined' | 'deferred' | 'failed';
+/**
+ * Delay for a debounce timer armed at `now` for a table not eligible until
+ * `nextEligibleAt`: the debounce, or the remaining duty-cycle cooldown when that
+ * is longer. Exported for the same reason {@link isStaleCount} is — the cooldown
+ * arithmetic is otherwise only observable through timing.
+ */
+export declare function armDelayMs(nextEligibleAt: number, now: number): number;
+/**
+ * Database internals the auto-analyze manager needs. Mirrors
+ * `WatcherManagerContext` — keeps the manager constructible without the full
+ * `Database`.
+ */
+export interface AutoAnalyzeManagerContext {
+    readonly schemaManager: Database['schemaManager'];
+    readonly options: Database['options'];
+    _findTable(tableName: string, schemaName?: string): ReturnType<Database['_findTable']>;
+    /**
+     * False while a transaction is open — an explicit `BEGIN…COMMIT` **and also** the
+     * implicit transaction a *writing* statement runs inside. Only the DML and DDL
+     * emitters call `_ensureTransaction`, so a read-only statement leaves this `true`,
+     * while every `insert` (`values` included — `runInsert` opens the transaction before
+     * it consumes its first row), `update`, `delete` and any DDL make it `false` for the
+     * rest of that statement. Since the refresh fires from a timer, it can land inside
+     * one of those and read `false` in a database the user considers to be in autocommit.
+     */
+    getAutocommit(): boolean;
+    /** Runs the refresh statement. Acquires the execution mutex — see the module doc. */
+    exec(sql: string): Promise<void>;
+}
+/** Per-table staleness bookkeeping. Keyed by lowercased `schema.table`. */
+export interface TableStalenessEntry {
+    /** Distinct rows changed by committed transactions since the last successful
+     *  statistics refresh. */
+    changedSinceAnalyze: number;
+    /** rowCount recorded by the last refresh this process observed; undefined = never. */
+    analyzedRowCount: number | undefined;
+    /** True once this crossing has been logged; cleared when the counter resets. */
+    staleLogged: boolean;
+    /** Armed debounce timer, if any. */
+    timer: ReturnType<typeof setTimeout> | undefined;
+    /** Resolves when the in-flight refresh for this table settles; undefined when idle. */
+    running: Promise<void> | undefined;
+    /** Epoch ms before which no refresh may start (duty-cycle cooldown / failure backoff). */
+    nextEligibleAt: number;
+    /** True once the oversize skip has been logged; cleared on a successful refresh. */
+    oversizeLogged: boolean;
+    /**
+     * Retries already spent on the current crossing after being deferred by an open
+     * transaction, capped at `AUTO_ANALYZE_MAX_DEFER_RETRIES`. Zeroed by a successful
+     * refresh and by any commit that touches the table, so it bounds one crossing's
+     * patience rather than the table's lifetime.
+     */
+    deferRetries: number;
+}
+/**
+ * The staleness threshold in changed rows:
+ *
+ * ```
+ * stale  ⟺  changedSinceAnalyze >= max(minMutations, ratio × knownRowCount)
+ * ```
+ *
+ * `knownRowCount` is 0 for a never-analyzed table (`SchemaManager` hardcodes
+ * `estimatedRows` to 0 at create), so the absolute floor governs exactly the
+ * case that matters most: bulk-loading rows into a fresh table trips
+ * `minMutations` long before any percentage of zero could.
+ *
+ * Precedent for the defaults: SQL Server's auto-update-stats uses 500 + 20% of
+ * rows; PostgreSQL's autoanalyze uses 50 + 10%.
+ */
+export declare function stalenessThreshold(minMutations: number, ratio: number, knownRowCount: number): number;
+/** Pure form of the staleness predicate — see {@link stalenessThreshold}. */
+export declare function isStaleCount(changedSinceAnalyze: number, minMutations: number, ratio: number, knownRowCount: number): boolean;
+/**
+ * Tracks committed-mutation drift per base table for a single `Database`, and
+ * schedules the background refresh that clears it.
+ */
+export declare class AutoAnalyzeManager {
+    private readonly ctx;
+    /**
+     * Lowercased `schema.table` → staleness bookkeeping. Same key convention the
+     * change log uses, so no re-derivation and no second key convention.
+     *
+     * NOTE: nothing here is persisted. After a restart the store backend's saved
+     * statistics still exist, but staleness accumulation restarts from zero — a
+     * table that drifted while the process was down looks fresh until it drifts
+     * again. Accepted for v1 (a restart is rare relative to the mutation
+     * threshold). If it ever matters, persist `changedSinceAnalyze` beside the
+     * table's statistics entry and reload it when the catalog loads.
+     */
+    private readonly entries;
+    private unsubscribeSchemaChanges;
+    /** Set by {@link dispose}; every scheduled path checks it before doing work. */
+    private disposed;
+    /** Refreshes that actually reached the `ANALYZE` statement. Test instrumentation. */
+    private refreshes;
+    constructor(ctx: AutoAnalyzeManagerContext);
+    private subscribeToSchemaChanges;
+    /**
+     * Fold one committed transaction's per-table changed-row counts into the
+     * staleness map and re-evaluate the threshold for every table it touched.
+     * Entries are created lazily on first touch.
+     */
+    recordCommit(counts: Map<string, number>): void;
+    /**
+     * Whether the named table (lowercased `schema.table`) has drifted past the
+     * threshold. Not a pure predicate: a table that has since disappeared answers
+     * `false` and has its entry dropped — see {@link knownRowCountOrDrop}.
+     */
+    isStale(key: string): boolean;
+    dispose(): void;
+    /** Cancel any armed timer for `entry`. Safe to call when none is armed. */
+    private clearTimer;
+    /** Forget a table, cancelling any refresh armed for it. */
+    private dropEntry;
+    /**
+     * Row count the ratio arm of the threshold applies to: what the last refresh
+     * this process observed reported, else whatever the catalog knows.
+     *
+     * Named for its side effect: a table that is gone (dropped between the commit
+     * and this lookup, or carried in from a detached schema) answers `undefined`
+     * AND has its entry evicted here, so every consumer of a row count doubles as
+     * the eviction path for stale keys. That is why {@link isStale} mutates.
+     */
+    private knownRowCountOrDrop;
+    private findTable;
+    /**
+     * Re-evaluate the threshold for one table after its counter moved: log the first
+     * crossing (a busy table must not flood the log) and arm a refresh.
+     */
+    private evaluate;
+    /** Schedule the debounced refresh for a table that has just crossed the threshold. */
+    private arm;
+    /**
+     * Begin a refresh, publish its settle promise on the entry, and act on how it
+     * ended. This is the single place that turns a {@link RefreshOutcome} into a
+     * scheduling decision — `refresh` itself only reports.
+     */
+    private start;
+    /** Decide what a finished refresh means for scheduling. */
+    private applyOutcome;
+    /**
+     * Reschedule a refusal that was purely about timing, on a geometric backoff and
+     * within a fixed budget. Once the budget is spent the crossing is dropped and the
+     * next commit that touches the table is what revives it.
+     */
+    private armDeferRetry;
+    /**
+     * Refresh one table's statistics, reporting how it ended. Never throws: a failed
+     * automatic refresh must not surface as an error on an unrelated user statement,
+     * and nothing awaits this.
+     *
+     * It decides nothing about scheduling — every exit names a {@link RefreshOutcome}
+     * and {@link start} decides what that means. A new early return therefore has to
+     * say whether it is a refusal or a deferral, which is what keeps "abandoned
+     * crossing" from being writable by accident.
+     */
+    private refresh;
+    /** Catalog row count for a table, ignoring the entry's own record. */
+    private catalogRowCount;
+    private enabled;
+    private minMutations;
+    private ratio;
+    /**
+     * Largest table (in known rows) an automatic refresh will scan; 0 disables the cap.
+     *
+     * NOTE: the gate is purely on row count. An earlier design also exempted modules
+     * whose `getStatistics()` answers the whole question cheaply, but no shipped module
+     * does — both the store backend (`store-table-base.ts`) and the memory backend
+     * (`vtab/memory/table.ts`) deliberately return an EMPTY `columnStats`, which
+     * `ANALYZE` reads as "size answered, scan for the rest". The exemption would be dead
+     * code. If a module that reports complete statistics ever appears, exempt it here.
+     */
+    private rowLimit;
+}
+//# sourceMappingURL=database-auto-analyze.d.ts.map

package/dist/src/core/database-auto-analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-auto-analyze.d.ts","sourceRoot":"","sources":["../../../src/core/database-auto-analyze.ts"],"names":[],"mappings":"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"}