@photostructure/sqlite
    Preparing search index...

    Class DatabasePool

    An experimental fixed-size pool of warm SQLite connections.

    SQL execution and connection lifecycle work run on libuv worker threads. Calls waiting for a connection stay in the JavaScript scheduler and consume no libuv worker.

    This API is experimental. Its compatibility policy is separate from the stable @photostructure/sqlite entry point, and it may change as production usage and benchmarks reveal better semantics.

    Only connection-independent operations are exposed. Prepared-statement handles, iteration, streaming, JavaScript transaction callbacks, user functions, sessions, changesets, backup, and serialization are deliberately omitted; use DatabaseSync for workloads needing that stateful surface.

    import { DatabasePool } from "@photostructure/sqlite/experimental";

    await using pool = await DatabasePool.open("app.db", {
      connections: 2,
      connectionSetup: [
        { sql: "PRAGMA journal_mode=WAL" },
        { sql: "PRAGMA busy_timeout=5000" },
      ],
    });

    await pool.run("INSERT INTO users(name) VALUES (?)", ["Ada"]);
    const users = await pool.all("SELECT * FROM users ORDER BY id");

    Experimental async database pool for ordering, concurrency, libuv sizing, and closing semantics.

    Index
    [asyncDispose] all batch close get run open

    • Closes the pool via close, so await using releases it on scope exit, including when an exception unwinds the scope.

      Returns Promise<void>

    • Run one statement on any available connection and return every row.

      The complete result is materialized natively before JavaScript objects are created on the event-loop thread, so a large result has a high peak memory footprint and its conversion can still pause JavaScript.

      Parameters

      • sql: string

        Exactly one executable SQL statement.

      • Optionalparams: PoolParams

      Returns Promise<PoolRow[]>

    • Run several operations sequentially on one leased connection, in one worker job. All SQL and parameters must be known when batch() is called.

      Use this when operations must share a connection or a transaction. Separate calls may be leased to different connections and complete in any order.

      Parameters

      • operations: readonly PoolOperation[]

        Descriptors to run, whose results are returned in order.

      • Optionaloptions: PoolBatchOptions

        Set transaction for all-or-nothing semantics.

      Returns Promise<PoolOperationResult[]>

      const results = await pool.batch(
        [
          { kind: "run", sql: "UPDATE account SET balance = balance - ? WHERE id = ?", params: [10, 1] },
          { kind: "run", sql: "UPDATE account SET balance = balance + ? WHERE id = ?", params: [10, 2] },
          { kind: "get", sql: "SELECT balance FROM account WHERE id = ?", params: [2] },
        ],
        { transaction: "immediate" },
      );

    • Close the pool. Closing begins immediately: new work is rejected, work already accepted drains, and then each physical connection closes exactly once.

      Idempotent; concurrent and repeated callers share one outcome.

      Returns Promise<void>

      Resolves once every connection has closed.

    • Run one statement on any available connection and return its first row.

      The statement still runs to completion, so INSERT ... RETURNING applies all of its changes even though only the first row is returned.

      Parameters

      • sql: string

        Exactly one executable SQL statement.

      • Optionalparams: PoolParams

      Returns Promise<PoolRow | undefined>

      The first row, or undefined when the statement produced none.

    • Run one statement on any available connection and discard its rows.

      Parameters

      • sql: string

        Exactly one executable SQL statement.

      • Optionalparams: PoolParams

      Returns Promise<PoolRunResult>

      The number of rows the statement changed. There is no lastInsertRowid; use INSERT ... RETURNING with get or all when generated values matter.

    • Open every connection in the pool, run DatabasePoolOptions.connectionSetup on each, and resolve once all of them are ready.

      Parameters

      • location: string | Buffer<ArrayBufferLike> | URL

        Database path, :memory:, or a SQLite URI. Buffer and URL locations are copied before the asynchronous open begins.

      • Optionaloptions: DatabasePoolOptions

        Pool configuration. Unknown keys are rejected.

      Returns Promise<DatabasePool>

      A pool ready to accept operations.

      If an option is invalid, if a multi-connection pool is requested for a private in-memory or temporary location, or if opening or setting up any connection fails. Connections opened before the failure are closed.

    Settings
    Member Visibility

    On This Page
    Methods