@vibesdotdev/localdb 0.0.2 → 1.0.0-rc.2

package/dist/core/connection-pool.d.ts

@@ -7,78 +7,236 @@
  * Features:
  * - Singleton pattern per database path
  * - Automatic WAL mode and busy timeout configuration
+ * - A bounded WAL (D-WAL, see `wal-policy.ts`): `journal_size_limit`; one
+ *   non-blocking checkpoint attempt per idle window (TRUNCATE, falling back to
+ *   RESTART after a busy attempt) with busy attempts backing off by whole
+ *   windows; an attempt on release to zero references and at close; observed
+ *   `(busy, log, checkpointed)` results with busy outcomes logged; and a bound
+ *   on how long a transaction may stay open
  * - Connection reuse across consumers
- * - Safe cleanup on process exit
+ * - Slow-statement reporting: a statement at or over `SLOW_STATEMENT_MS` on any
+ *   pooled connection is recorded with its operation and table, and the tick
+ *   reports it (see `slow-statement.ts`) — value-free, and never from the
+ *   statement's own path
+ * - Explicit, host-owned cleanup
  * - Connection statistics and monitoring
+ *
+ * The pool never deletes a raw `-wal` or `-shm` file.
+ *
+ * Hosts sharing one pool have at most one connection per path: two connections to one
+ * file on the same thread can wait on each other inside SQLite's synchronous
+ * busy handler. A composition root that boots several runtimes in one process
+ * creates the pool explicitly (`createConnectionPool`) and hands it to every
+ * runtime it boots (`shareConnectionPool`), so those runtimes — including
+ * reload-generation forks, which inherit the registration — share the one
+ * connection per path. A process that boots a single runtime uses the
+ * runtime-owned default the LocalDB plugin registers instead. Each call
+ * reports on the runtime it was handed (C083a), never on an ambient default.
+ *
+ * Maintenance is owned by a runtime lifecycle (RC07). A connection records the
+ * runtimes that acquired it and runs its maintenance tick on the lifecycle of
+ * one of them that is live and persistent; when that lifecycle ends, the tick
+ * ends with it and moves to the next live persistent holder. The reload
+ * generation dispatcher reads whichever generation serves: it stays a holder
+ * while it serves a live one, so its tick follows it from a retiring
+ * generation to the next. A connection no persistent runtime
+ * holds gets no tick: it checkpoints on release to zero references and on
+ * close/shutdown instead, until a persistent runtime acquires it again.
  */
-import { Database } from 'bun:sqlite';
-export interface PooledConnection {
-    db: Database;
-    refCount: number;
-    lastUsed: number;
-    createdAt: number;
-    consumer: string;
-}
-export interface ConnectionStats {
-    total: number;
-    active: number;
-    idle: number;
-    connections: Array<{
-        path: string;
-        refCount: number;
-        ageMs: number;
-        consumer: string;
-    }>;
-}
-declare class SQLiteConnectionPool {
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+export { PoolDescriptorSchema, type PoolDescriptor } from '../schemas/pool.ts';
+import type { ConnectionStats } from '../schemas/api.ts';
+import type { SqliteConnection } from '../driver/sqlite-driver.ts';
+export type { ConnectionStats, PooledConnection, WalCheckpointTrigger } from '../schemas/api.ts';
+export declare class SQLiteConnectionPool {
     private connections;
-    private cleanupInterval?;
+    /** Physical path custody spans every runtime-local manager using this pool. */
+    private readonly databasePathLocks;
     private readonly STALE_THRESHOLD_MS;
-    private readonly CLEANUP_INTERVAL_MS;
-    constructor();
+    /** Opens in flight, by path: concurrent first acquisitions share one connection. */
+    private readonly opening;
+    /** Serialize managed initialization, migration, release and reset against the same physical file. */
+    withDatabasePathLock<T>(dbPath: string, task: () => Promise<T>): Promise<T>;
+    /**
+     * Get or create a database connection with optimal configuration, opened
+     * through the SQLite driver the calling runtime's host registered. The
+     * calling runtime becomes a holder of the connection and reports the open.
+     * A runtime whose disposal began is refused before any connection opens
+     * (`CANCELLED` `runtime-disposed`), and again if it began while the open
+     * was in flight. Cancellation before publication closes the startup handle.
+     */
+    getConnection(runtime: RuntimeRef, dbPath: string, consumer?: string): Promise<SqliteConnection>;
+    /** Open and pool the connection at `dbPath` with the LocalDB pragmas, through the runtime's driver. */
+    private open;
+    /**
+     * Record `runtime` as a holder of the pooled connection at `dbPath`, so its
+     * maintenance can run on (or move to) that runtime. No connection there:
+     * nothing to hold.
+     */
+    retain(runtime: RuntimeRef, dbPath: string): void;
+    private hold;
     /**
-     * Get or create a database connection with optimal configuration
+     * Keep the connection's tick on a live persistent holder. A tick whose
+     * lifecycle (the one it started on) is still live, on a runtime that still
+     * holds the connection, stays where it is;
+     * otherwise the first live persistent holder takes it, and holders that
+     * ended are dropped.
      */
-    getConnection(dbPath: string, consumer?: string): Database;
+    private ensureMaintenance;
     /**
-     * Configure database with optimal settings for concurrent access
+     * Run the connection's tick on the lifecycle `runtime` reads now. The tick
+     * ends when that lifecycle ends (it clears every interval). At that moment
+     * the runtime is dropped as a holder unless it now reads a live lifecycle
+     * (the reload generation dispatcher, whose `lifecycle` follows whichever
+     * generation serves), and the tick moves to the next live persistent
+     * holder, that runtime included.
      */
-    private configureDatabase;
+    private maintainOn;
+    /** One maintenance tick for one connection. It never throws into the timer: a failure is logged with its cause. */
+    private tick;
     /**
      * Release a connection (decrement reference count)
      * Connection remains in pool for reuse
      */
-    releaseConnection(dbPath: string): void;
+    releaseConnection(runtime: RuntimeRef, dbPath: string): void;
     /**
-     * Close a specific connection immediately
-     * Only closes if reference count is zero (unless forced)
+     * Run one observed, non-blocking checkpoint attempt and record its outcome,
+     * reported on `runtime`. A busy attempt is logged at warn (a run of
+     * {@link WAL_BUSY_STARVATION_THRESHOLD} at error, as starvation), switches
+     * the next attempt's mode, and backs the connection off by whole windows. A
+     * checkpoint SQLite itself rejects is logged at error with its cause and
+     * never blocks the caller's close or tick.
      */
-    closeConnection(dbPath: string, force?: boolean): boolean;
+    private observeCheckpoint;
     /**
-     * Clean up stale connections (unused for 30+ minutes with zero references)
+     * Bound how long a pooled connection may sit inside a transaction. SQLite
+     * is synchronous, so a transaction a tick can observe spans an `await`; one
+     * older than {@link MAX_TRANSACTION_AGE_MS} pins every WAL frame written
+     * after it began, in every process. It is rolled back and reported; the
+     * owner's later COMMIT then fails loudly rather than the WAL growing silently.
+     *
+     * @returns whether the connection is still inside a transaction.
      */
-    private cleanupStale;
+    private enforceTransactionBound;
     /**
-     * Start periodic cleanup
+     * Report the statements this window recorded as slow, on `runtime` and once
+     * per connection. Each report carries the connection's consumer and database
+     * with the statement's operation and table; a window that recorded more than
+     * it kept says so rather than reading as a complete count.
      */
-    private startCleanup;
+    private reportSlowStatements;
     /**
-     * Stop periodic cleanup
+     * One idle window for one connection: report what it recorded as slow, bound
+     * an open transaction, close the connection when it has been unused for 30+
+     * minutes with zero references, or make at most one observed checkpoint
+     * attempt when it is not inside a transaction and not backing off. Every step
+     * reports its own failure.
      */
-    private stopCleanup;
+    private maintainConnection;
     /**
-     * Close all connections (typically on shutdown)
+     * One maintenance pass over every pooled connection, reported on `runtime`.
+     * Each connection's lifecycle tick runs the same window for that connection
+     * alone; hosts and tests may call this directly.
      */
-    closeAll(): void;
+    maintain(runtime: RuntimeRef, now?: number): void;
     /**
-     * Get pool statistics
+     * Close one pooled connection and remove it from the pool, reported on
+     * `runtime`. A connection still inside a transaction is closed without a
+     * checkpoint, and SQLite discards that transaction: the discard is
+     * reported, never silent. A close SQLite refuses throws
+     * `localdb-close-failed` (the original error as `cause`) and the connection
+     * stays pooled, still maintained, for a retry.
      */
-    getStats(): ConnectionStats;
+    private closePooled;
     /**
-     * Register process exit handlers for cleanup
+     * Refuse destructive replacement while another lifecycle or pooled reference
+     * holds the file. Only the requesting instance's actual open connection may
+     * account for one reference; legacy/raw borrowers keep their custody too.
+     * Call under the database path lock, before releasing or closing anything.
      */
-    private registerExitHandlers;
+    assertCanReplaceDatabase(runtime: RuntimeRef, dbPath: string, ownedConnection?: SqliteConnection): void;
+    /**
+     * Give back one pooled reference no live runtime holds: every recorded
+     * holder ended (or none is recorded) while the reference count is still
+     * nonzero — typically a client of a runtime that ended without releasing.
+     * Returns whether a reference was given back. A connection another live
+     * runtime still holds is never touched.
+     */
+    releaseOrphanedConnection(dbPath: string): boolean;
+    /**
+     * Close a specific connection immediately. Only closes if the reference
+     * count is zero, unless forced. Returns whether it closed; a close SQLite
+     * refuses throws `localdb-close-failed` and leaves the connection pooled.
+     */
+    closeConnection(runtime: RuntimeRef, dbPath: string, force?: boolean): boolean;
+    /**
+     * Give back every connection `runtime` holds (typically at its disposal),
+     * reported on `runtime`; runtimes that ended hold nothing. A connection
+     * another live runtime still holds (another root, or the root a disposing
+     * reload generation was forked from) stays pooled for it, its maintenance moving to that
+     * holder; every other connection closes. Every close is attempted; the ones
+     * SQLite refuses stay pooled and are reported together in one AggregateError
+     * so the runtime owner can report them and retry.
+     */
+    closeAll(runtime: RuntimeRef, retainedPaths?: ReadonlySet<string>): void;
+    /** Whether a managed handle still names the pooled connection at this path. */
+    ownsConnection(dbPath: string, db: SqliteConnection): boolean;
+    /**
+     * Get pool statistics
+     */
+    getStats(): ConnectionStats;
 }
-export declare const connectionPool: SQLiteConnectionPool;
-export {};
+/**
+ * The `localdb/pool` kind: the process's physical SQLite connections, owned
+ * through the kernel. The pool holds live host handles, so — unlike migration
+ * declarations, which each runtime owns separately — runtimes that must open
+ * the same file share one pool instance resolved from the runtime they are
+ * handed. No module-level pool instance exists: every instance is created
+ * explicitly (`createConnectionPool`, the plugin default, or a shared owner a
+ * composition root registers) and resolved through the kernel below.
+ */
+export declare const LOCALDB_POOL_KIND = "localdb/pool";
+/** The runtime-owned default pool, created per root runtime by the LocalDB plugin. */
+export declare const DEFAULT_POOL_ID = "pool";
+/**
+ * An explicitly shared pool, handed to each runtime by the composition root
+ * that boots them. Preferred over the default whenever it is registered.
+ */
+export declare const SHARED_POOL_ID = "shared";
+/** The kind LocalDB registers; an implementation that is not a pool is refused `implementation-invalid`. */
+export declare const poolKind: import("@vibesdotdev/kernel").RuntimeKindDescriptorRecord<SQLiteConnectionPool>;
+/**
+ * Create the physical connection pool a composition root hands to the runtimes
+ * it boots. One pool per process per database set: every runtime handed the
+ * same pool shares the one connection per path.
+ */
+export declare function createConnectionPool(): SQLiteConnectionPool;
+/**
+ * Resolve the runtime's physical connection pool through the kernel on every
+ * call, so current selection, invalidation, and implementation caching remain
+ * owned by the runtime: an explicitly shared pool when the composition root
+ * registered one, else the runtime-owned default the LocalDB plugin
+ * registered. Anything else (a refused loader, an invalid implementation)
+ * propagates unwrapped.
+ */
+export declare function poolOf(runtime: RuntimeRef): Promise<SQLiteConnectionPool>;
+/**
+ * The already-resolved pool, or `undefined` when no resolution warmed the
+ * kernel cache yet. Synchronous cover for call sites that hold no async
+ * context after an async call resolved the pool first.
+ */
+export declare function tryPoolOf(runtime: RuntimeRef): SQLiteConnectionPool | undefined;
+/**
+ * Register the runtime-owned default pool, unless one is already registered:
+ * reload-generation forks inherit their root's registrations, so they keep
+ * sharing the root's pool instead of minting a second connection per path.
+ */
+export declare function ensureDefaultPool(runtime: RuntimeRef): void;
+/**
+ * Hand one explicitly created pool to a runtime: every runtime the
+ * composition root boots against the same database files shares the one
+ * connection per path. Fork generations inherit the registration, so they
+ * share it too.
+ */
+export declare function shareConnectionPool(runtime: RuntimeRef, pool: SQLiteConnectionPool): void;
 //# sourceMappingURL=connection-pool.d.ts.map

package/dist/core/connection-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection-pool.d.ts","sourceRoot":"","sources":["../../src/core/connection-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAMtC,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,QAAQ,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,KAAK,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACH;AAED,cAAM,oBAAoB;IACzB,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,eAAe,CAAC,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAkB;IACrD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAiB;;IAUrD;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAY,GAAG,QAAQ;IA2B7D;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;OAGG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQvC;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,OAAO;IAoBvD;;OAEG;IACH,OAAO,CAAC,YAAY;IAWpB;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAgBhB;;OAEG;IACH,QAAQ,IAAI,eAAe;IA6B3B;;OAEG;IACH,OAAO,CAAC,oBAAoB;CAW5B;AAGD,eAAO,MAAM,cAAc,sBAA6B,CAAC"}
+{"version":3,"file":"connection-pool.d.ts","sourceRoot":"","sources":["../../src/core/connection-pool.ts"],"names":[],"mappings":"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"}