@vibeorm/adapter-bun 1.3.0 → 2.0.0-alpha.10

package/src/index.ts

@@ -1,621 +0,0 @@
-/**
- * @vibeorm/adapter-bun — Bun's native SQL adapter for VibeORM.
- *
- * Uses Bun's built-in `bun:sql` driver for high-performance PostgreSQL
- * connections. Supports optional prepared statement caching via synthetic
- * tagged templates.
- */
-
-import type { DatabaseAdapter, QueryResult, TransactionOptions } from "@vibeorm/runtime";
-import { PgArray } from "@vibeorm/runtime";
-
-export type BunAdapterOptions = {
-  /** PostgreSQL connection URL. Falls back to DATABASE_URL env var if not provided. */
-  url?: string;
-  /** Maximum number of connections in the pool (default: 10). */
-  max?: number;
-  /**
-   * Default statement timeout in milliseconds for all queries (default: none).
-   *
-   * Sets PostgreSQL's `statement_timeout` as a connection-level startup parameter,
-   * so every query on every connection inherits it automatically with zero per-query
-   * overhead. Queries exceeding this duration are cancelled by PostgreSQL with
-   * SQLSTATE 57014, which VibeORM surfaces as a `VibeTransientError` with code
-   * `STATEMENT_TIMEOUT`.
-   *
-   * Transaction-level `timeout` (via `$transaction` options) overrides this default
-   * for the duration of that transaction using `SET LOCAL statement_timeout`.
-   *
-   * Recommended: Set to a value appropriate for your workload (e.g. 30000 for
-   * general use, 250–1000 for latency-sensitive OLTP services).
-   */
-  statementTimeout?: number;
-  /**
-   * Maximum time in milliseconds to wait when establishing a new connection (default: none).
-   *
-   * Maps directly to bun:sql's `connectionTimeout` constructor option (which expects
-   * seconds — we convert ms → seconds for you). If a connection cannot be established
-   * within this duration, bun:sql throws `ERR_POSTGRES_CONNECTION_TIMEOUT`.
-   *
-   * Note: this is for the initial TCP/handshake establishment, NOT for waiting on
-   * pool checkout once the pool is saturated.
-   *
-   * Historically this was injected as a `connect_timeout=…` URL parameter, but
-   * bun:sql forwards unrecognised URL parameters to PostgreSQL as runtime
-   * configuration settings, and `connect_timeout` is a libpq *client-side* option
-   * (not a server GUC), so PostgreSQL would error with
-   * `unrecognized configuration parameter "connect_timeout"`. The constructor
-   * option is the canonical way to set it.
-   */
-  connectionTimeout?: number;
-  /**
-   * Whether to use named prepared statements for read queries (default: false).
-   *
-   * When `true`, the adapter caches SQL texts as synthetic tagged templates,
-   * creating named prepared statements that PostgreSQL caches execution plans for.
-   * This saves ~0.1ms of planning time per query but can cause PostgreSQL to
-   * switch to a "generic plan" after 5 executions, which may choose a worse
-   * index for queries with range filters or skewed data distributions.
-   *
-   * When `false` (default), the adapter uses `sql.unsafe()` which bypasses
-   * bun:sql's tagged template / named statement path. PostgreSQL replans each
-   * execution using the actual parameter values, always choosing the optimal index.
-   *
-   * Note: The bun:sql `prepare` constructor option is always left at its default
-   * (`true`). Setting `prepare: false` on the constructor triggers a bun:sql
-   * performance regression (~28ms per query on remote databases). Instead, we
-   * only control the execution path: `sql.unsafe()` vs tagged templates.
-   *
-   * Recommendation: Leave as `false` unless profiling shows planning overhead
-   * is a bottleneck (rare — typically only for sub-millisecond queries at
-   * very high throughput).
-   */
-  preparedStatements?: boolean;
-  /**
-   * Maximum number of entries in the prepared statement cache (default: 1000).
-   * Only used when `preparedStatements: true`.
-   * Prevents unbounded memory growth in long-running processes.
-   * Each unique SQL text consumes one slot. LRU eviction when full.
-   */
-  stmtCacheMax?: number;
-  /**
-   * Controls PostgreSQL's plan caching behavior for prepared statements
-   * (default: `"force_custom_plan"`).
-   *
-   * bun:sql uses the extended query protocol, which creates implicit prepared
-   * statements internally. After ~5 executions of the same query text,
-   * PostgreSQL may switch to a "generic plan" that ignores actual parameter
-   * values. This causes significant performance regressions for queries with
-   * range filters (`>=`, `<=`, `BETWEEN`), pattern matching (`LIKE`), or
-   * skewed data distributions — the planner picks sequential scans instead
-   * of index scans because it can't estimate selectivity without real values.
-   *
-   * - `"force_custom_plan"` (default): Always generates plans using actual
-   *   parameter values. Costs ~0.1 ms extra planning per query but always
-   *   picks the optimal index. Recommended for most workloads.
-   * - `"auto"`: PostgreSQL's default — switches to generic plans after ~5
-   *   executions if the estimated cost is similar. Can cause 2-4× regressions
-   *   on filtered COUNT / aggregate queries.
-   * - `"force_generic_plan"`: Always uses generic plans (not recommended).
-   *
-   * Injected via the PostgreSQL `options` startup parameter so it applies to
-   * every connection in the pool automatically. Requires PostgreSQL 12+.
-   */
-  planCacheMode?: "auto" | "force_custom_plan" | "force_generic_plan";
-};
-
-// ─── Internal bun:sql types ───────────────────────────────────────
-
-/**
- * A bun:sql "reserved" connection (single physical connection checked out
- * from the pool). Used by the manual `BEGIN … COMMIT` transaction path.
- *
- * Note: a reserved connection has NO `.begin()` or `.reserve()` — any nested
- * transaction must be implemented via SAVEPOINTs on the same connection.
- */
-type SqlReserved = {
-  (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
-  unsafe(query: string, values?: unknown[]): Promise<unknown[]>;
-  release(): void;
-};
-
-/**
- * The transactional handle passed to the `sql.begin(callback)` callback.
- * Modern bun:sql exposes `.savepoint(fn)` which creates a savepoint-scoped
- * sub-transaction (the correct API for nested transactions). Calling
- * `.begin()` here throws "cannot call begin inside a transaction use
- * savepoint() instead" — so we always prefer `savepoint` when present.
- *
- * Older / minimal bun:sql versions may lack `.savepoint`, in which case we
- * fall back to explicit `SAVEPOINT <name>` SQL via `.unsafe()`.
- */
-type SqlTransaction = {
-  (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
-  unsafe(query: string, values?: unknown[]): Promise<unknown[]>;
-  savepoint?: <T>(fn: (tx: SqlTransaction) => Promise<T>) => Promise<T>;
-};
-
-type SqlInstance = {
-  (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
-  unsafe(query: string, values?: unknown[]): Promise<unknown[]>;
-  begin<T>(fn: (tx: SqlTransaction) => Promise<T>): Promise<T>;
-  reserve(): Promise<SqlReserved>;
-  close(): Promise<void>;
-};
-
-/**
- * Anything that can execute SQL through bun:sql — pool, reserved connection,
- * or in-transaction handle. Used by the unified adapter created at every
- * nesting level.
- */
-type SqlSource = SqlInstance | SqlReserved | SqlTransaction;
-
-/**
- * Whether the SQL source is the outermost pool (can issue real BEGIN/COMMIT
- * or use `sql.begin()`) or is already inside a transaction (must use
- * SAVEPOINTs for nesting).
- */
-type ParentMode = "pool" | "tx";
-
-/** Shared monotonic counter for savepoint naming across one top-level tx. */
-type SavepointCounter = { n: number };
-
-/**
- * Create a VibeORM database adapter using Bun's built-in SQL driver.
- *
- * @example
- * ```ts
- * import { bunAdapter } from "@vibeorm/adapter-bun";
- * import { VibeClient } from "./generated/vibeorm";
- *
- * const db = VibeClient({
- *   adapter: bunAdapter({ url: "postgres://...", max: 10 }),
- * });
- *
- * // With prepared statements enabled (for high-throughput local scenarios)
- * const db2 = VibeClient({
- *   adapter: bunAdapter({ url: "postgres://...", preparedStatements: true }),
- * });
- * ```
- */
-export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
-  const USE_PREPARED = options?.preparedStatements ?? false;
-  const STMT_CACHE_MAX = options?.stmtCacheMax ?? 1000;
-  const PLAN_CACHE_MODE = options?.planCacheMode ?? "force_custom_plan";
-  const stmtCache = new Map<string, TemplateStringsArray>();
-
-  let sqlInstance: SqlInstance | null = null;
-
-  /**
-   * Append a PostgreSQL `options` startup parameter to a connection URL.
-   * The `options` parameter is sent during connection establishment, so it
-   * applies to every connection created by bun:sql's internal pool.
-   */
-  function appendStartupOption(params: { url: string; option: string }): string {
-    const { url, option } = params;
-    const separator = url.includes("?") ? "&" : "?";
-    return `${url}${separator}options=${encodeURIComponent(option)}`;
-  }
-
-  /**
-   * Resolve the connection URL, injecting startup parameters as needed.
-   * Falls back to DATABASE_URL env var when no explicit URL is provided.
-   *
-   * Injects via the PostgreSQL `options` startup parameter (server-side runtime
-   * configuration; valid because `options` is a real Postgres startup-protocol
-   * parameter that the server parses for `-c key=value` settings):
-   * - plan_cache_mode (unless "auto")
-   * - statement_timeout (if configured)
-   *
-   * `connect_timeout` is NOT injected here — it's a libpq client-side option,
-   * not a server GUC, and bun:sql would forward it to the server as an
-   * unrecognised configuration parameter. We pass it via the bun:sql
-   * `connectionTimeout` constructor option instead (see getSql()).
-   */
-  function resolveConnectionUrl(): string | undefined {
-    const STATEMENT_TIMEOUT = options?.statementTimeout;
-
-    // Build startup options string (for -c parameters)
-    const startupParts: string[] = [];
-    if (PLAN_CACHE_MODE !== "auto") {
-      startupParts.push(`-c plan_cache_mode=${PLAN_CACHE_MODE}`);
-    }
-    if (STATEMENT_TIMEOUT !== undefined) {
-      startupParts.push(`-c statement_timeout=${Number(STATEMENT_TIMEOUT)}`);
-    }
-
-    const needsUrlMutation = startupParts.length > 0;
-    if (!needsUrlMutation) return options?.url;
-
-    const baseUrl = options?.url ?? process.env.DATABASE_URL;
-    if (!baseUrl) return undefined;
-
-    return appendStartupOption({
-      url: baseUrl,
-      option: startupParts.join(" "),
-    });
-  }
-
-  function getSql(): SqlInstance {
-    if (sqlInstance) return sqlInstance;
-
-    // Import Bun's SQL
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { SQL } = require("bun");
-
-    const sqlOptions: Record<string, unknown> = {
-      max: options?.max ?? 10,
-      // Note: We intentionally do NOT set `prepare: false` here.
-      // Setting prepare=false on the bun:sql constructor triggers a performance
-      // regression (~28ms per query on remote/SSL databases) due to a bun:sql
-      // internal behavior change. Instead, we control prepared statement usage
-      // at the execution level: sql.unsafe() for the default path (no named stmts)
-      // vs tagged templates for the preparedStatements=true path.
-      // See: https://github.com/oven-sh/bun/issues/20294
-    };
-
-    // Connection establishment timeout — bun:sql expects seconds.
-    // We accept milliseconds in our public API to stay consistent with pgAdapter
-    // and Node convention, then convert here.
-    if (options?.connectionTimeout !== undefined) {
-      sqlOptions.connectionTimeout = Math.max(1, Math.ceil(options.connectionTimeout / 1000));
-    }
-
-    const connectionUrl = resolveConnectionUrl();
-    if (connectionUrl) {
-      sqlInstance = new SQL(connectionUrl, sqlOptions) as unknown as SqlInstance;
-    } else {
-      // No URL resolved — bun:sql will use PG* env vars.
-      // Startup parameters (plan_cache_mode, statement_timeout) cannot be
-      // injected via URL options in this case (would need SET on connect).
-      sqlInstance = new SQL(sqlOptions) as unknown as SqlInstance;
-    }
-
-    return sqlInstance;
-  }
-
-  /**
-   * LRU-bounded synthetic tagged template cache for prepared statement reuse.
-   * bun:sql tagged templates create named prepared statements that PostgreSQL
-   * caches execution plans for. By converting dynamic SQL into synthetic tagged
-   * templates with stable references, we get the same caching behavior.
-   *
-   * Only used when `preparedStatements: true`.
-   */
-  function getOrCreateTemplate(params: { text: string }): TemplateStringsArray {
-    const { text } = params;
-    let strings = stmtCache.get(text);
-    if (strings) {
-      // Move to end (most recently used) by re-inserting
-      stmtCache.delete(text);
-      stmtCache.set(text, strings);
-      return strings;
-    }
-    const parts = text.split(/\$\d+/);
-    strings = Object.assign(parts, { raw: parts }) as unknown as TemplateStringsArray;
-    // Evict oldest entry if at capacity
-    if (stmtCache.size >= STMT_CACHE_MAX) {
-      const oldestKey = stmtCache.keys().next().value;
-      if (oldestKey !== undefined) stmtCache.delete(oldestKey);
-    }
-    stmtCache.set(text, strings);
-    return strings;
-  }
-
-  /**
-   * Convert a JS array to a PostgreSQL array literal string `{val1,val2,...}`.
-   * bun:sql's extended query protocol sends values as strings, so PostgreSQL
-   * needs array parameters in its native array literal format.
-   *
-   * Element handling:
-   *  - `null` / `undefined` → `NULL`
-   *  - `number` / `bigint` / `boolean` → unquoted primitive
-   *  - `Date` → ISO-8601 string (quoted+escaped) so PG can parse it as
-   *    `timestamp[]` / `timestamptz[]`. Using the default `String(d)` would
-   *    yield a non-ISO format like `Mon May 24 2026 …` that PG cannot parse.
-   *  - `Buffer` / `Uint8Array` → not supported inside array literals; throw
-   *    a clear error instead of silently producing `[object Object]`.
-   *  - `string` → quoted with `"`/`\` escaping
-   *  - other `object` → `JSON.stringify` then quoted+escaped (covers users
-   *    putting plain objects into a `Json[]` / `Jsonb[]` scalar list).
-   */
-  function toPgArrayLiteral(arr: unknown[]): string {
-    const escape = (str: string): string =>
-      `"${str.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-
-    const escaped = arr.map((v) => {
-      if (v === null || v === undefined) return "NULL";
-      if (typeof v === "number" || typeof v === "bigint" || typeof v === "boolean") {
-        return String(v);
-      }
-      if (v instanceof Date) {
-        return escape(v.toISOString());
-      }
-      if (Buffer.isBuffer(v) || v instanceof Uint8Array) {
-        throw new Error(
-          "toPgArrayLiteral: Buffer/Uint8Array array elements are not supported"
-        );
-      }
-      if (typeof v === "string") {
-        return escape(v);
-      }
-      if (typeof v === "object") {
-        return escape(JSON.stringify(v));
-      }
-      return escape(String(v));
-    });
-    return `{${escaped.join(",")}}`;
-  }
-
-  /**
-   * Normalise raw-path parameter values for bun:sql.
-   *
-   * bun:sql's extended query protocol sends params as strings, so a plain JS
-   * array binding cannot be auto-converted to a PG array literal by the driver.
-   * The ORM hot path wraps array params in `PgArray` and converts them via
-   * `formatArrayParam` before they reach the adapter — but raw queries
-   * (`$queryRawUnsafe`, `$queryRaw` template-literal, `$executeRaw*`) hand the
-   * user's array straight through.
-   *
-   * To make `db.$queryRawUnsafe('… WHERE "id" = ANY($1)', [1,2,3])` actually
-   * match rows, we convert any plain JS array element in the param list to a
-   * PG array literal here. Non-array values pass through unchanged so that
-   * bun:sql's native handling (numbers, strings, Dates, Buffers, plain objects
-   * for json columns when bun supports it) remains in effect.
-   */
-  function normalizeRawValues(values: unknown[] | undefined): unknown[] | undefined {
-    if (!values || values.length === 0) return values;
-    let mutated: unknown[] | null = null;
-    for (let i = 0; i < values.length; i++) {
-      const v = values[i];
-      if (Array.isArray(v)) {
-        if (!mutated) mutated = values.slice();
-        mutated[i] = toPgArrayLiteral(v);
-      }
-    }
-    return mutated ?? values;
-  }
-
-  /**
-   * Execute a query using the configured strategy.
-   * - preparedStatements=true: uses synthetic tagged templates (named prepared stmts)
-   * - preparedStatements=false: uses sql.unsafe() (replanned each time)
-   *
-   * Note: this is the ORM hot path. Scalar-list / `= ANY()` array values are
-   * already wrapped in `PgArray` by the query builder and converted to a PG
-   * array literal string via `formatArrayParam` before they reach here, so we
-   * intentionally do NOT touch raw JS arrays here (that would corrupt JSON
-   * column writes that genuinely pass a JS array as a JSON value).
-   */
-  async function executeQuery(sql: SqlInstance, params: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]> {
-    // Defence-in-depth: if any value is a runtime PgArray that slipped through
-    // (e.g. a caller bypassed `client.ts`'s formatArrayParam unwrap), convert
-    // it to the PG array literal string that bun:sql actually needs. The
-    // standard ORM path has already done this conversion via `formatArrayParam`,
-    // so the loop is a near-zero-cost guard for the normal case.
-    // Bug 3 — see .ai/bug-report-2026-05-24.md.
-    let values: unknown[] = params.values;
-    for (let i = 0; i < params.values.length; i++) {
-      if (params.values[i] instanceof PgArray) {
-        if (values === params.values) values = params.values.slice();
-        values[i] = toPgArrayLiteral((params.values[i] as PgArray).values);
-      }
-    }
-    if (USE_PREPARED) {
-      const strings = getOrCreateTemplate({ text: params.text });
-      const result = await sql(strings, ...values);
-      return result as Record<string, unknown>[];
-    }
-    const result = await sql.unsafe(params.text, values);
-    return result as Record<string, unknown>[];
-  }
-
-  function isolationLevelToSql(params: { level: NonNullable<TransactionOptions["isolationLevel"]> }): string {
-    switch (params.level) {
-      case "ReadCommitted": return "READ COMMITTED";
-      case "RepeatableRead": return "REPEATABLE READ";
-      case "Serializable": return "SERIALIZABLE";
-    }
-  }
-
-  /**
-   * Build the typed adapter facade over any bun:sql source — the pool, a
-   * reserved connection, or an in-transaction handle. The `parentMode`
-   * discriminator tells `.transaction()` whether a nested call should issue
-   * a real BEGIN/COMMIT (or `sql.begin()`) at the pool level, or open a
-   * SAVEPOINT on the current connection.
-   *
-   * `savepointCounter` is shared by reference across every adapter created
-   * for one top-level transaction, so sibling and deeply-nested transactions
-   * always get distinct savepoint names like `vibeorm_sp_0`, `vibeorm_sp_1`,
-   * `vibeorm_sp_2`, …
-   */
-  function createAdapter(params: {
-    sql: SqlSource;
-    parentMode: ParentMode;
-    savepointCounter: SavepointCounter;
-  }): DatabaseAdapter {
-    const { sql, parentMode, savepointCounter } = params;
-
-    async function txViaSavepoint<T>(innerFn: (txAdapter: DatabaseAdapter) => Promise<T>): Promise<T> {
-      // We're inside a transaction already — open a SAVEPOINT on this
-      // connection. Prefer the driver's native `tx.savepoint()` if exposed
-      // (modern bun:sql); else fall back to explicit `SAVEPOINT` SQL on
-      // either the in-tx handle (which lacks `.savepoint`) or a reserved
-      // connection holding a manual `BEGIN`.
-      const txSql = sql as SqlTransaction;
-      if (typeof txSql.savepoint === "function") {
-        return txSql.savepoint(async (sp) => {
-          const nestedAdapter = createAdapter({
-            sql: sp,
-            parentMode: "tx",
-            savepointCounter,
-          });
-          return innerFn(nestedAdapter);
-        });
-      }
-
-      // Fallback: explicit SAVEPOINT via unsafe(). The counter is shared by
-      // reference, so sibling/nested SAVEPOINTs never collide.
-      const spName = `vibeorm_sp_${savepointCounter.n++}`;
-      await txSql.unsafe(`SAVEPOINT ${spName}`);
-      try {
-        const nestedAdapter = createAdapter({
-          sql: txSql,
-          parentMode: "tx",
-          savepointCounter,
-        });
-        const result = await innerFn(nestedAdapter);
-        await txSql.unsafe(`RELEASE SAVEPOINT ${spName}`);
-        return result;
-      } catch (err) {
-        // Best-effort rollback — mirror pg adapter behaviour so we never
-        // mask the original error if the ROLLBACK itself fails.
-        try { await txSql.unsafe(`ROLLBACK TO SAVEPOINT ${spName}`); } catch { /* rollback best-effort */ }
-        throw err;
-      }
-    }
-
-    async function txViaPool<T>(
-      innerFn: (txAdapter: DatabaseAdapter) => Promise<T>,
-      options?: TransactionOptions
-    ): Promise<T> {
-      const pool = sql as SqlInstance;
-
-      // Fast path: no custom options — use native sql.begin() for best perf.
-      if (!options?.isolationLevel && !options?.timeout) {
-        return pool.begin(async (txSql: SqlTransaction) => {
-          const txAdapter = createAdapter({
-            sql: txSql,
-            parentMode: "tx",
-            savepointCounter,
-          });
-          return innerFn(txAdapter);
-        });
-      }
-
-      // Manual path: reserve a single connection for custom BEGIN options.
-      const reserved = await pool.reserve();
-      try {
-        const isolation = options.isolationLevel
-          ? ` ISOLATION LEVEL ${isolationLevelToSql({ level: options.isolationLevel })}`
-          : "";
-        await reserved.unsafe(`BEGIN${isolation}`);
-
-        if (options.timeout) {
-          await reserved.unsafe(`SET LOCAL statement_timeout = ${Number(options.timeout)}`);
-        }
-
-        const txAdapter = createAdapter({
-          sql: reserved,
-          parentMode: "tx",
-          savepointCounter,
-        });
-        const result = await innerFn(txAdapter);
-        await reserved.unsafe("COMMIT");
-        return result;
-      } catch (err) {
-        try { await reserved.unsafe("ROLLBACK"); } catch { /* rollback best-effort */ }
-        throw err;
-      } finally {
-        reserved.release();
-      }
-    }
-
-    return {
-      async execute(execParams) {
-        return executeQuery(sql as SqlInstance, execParams);
-      },
-
-      async executeUnsafe(execParams) {
-        const values = normalizeRawValues(execParams.values);
-        const result = await sql.unsafe(execParams.text, values);
-        const resultAny = result as unknown as Record<string, unknown>;
-        let affectedRows: number;
-        if (typeof resultAny.count === "number") {
-          affectedRows = resultAny.count;
-        } else if (typeof resultAny.affectedRows === "number") {
-          affectedRows = resultAny.affectedRows;
-        } else {
-          affectedRows = (result as unknown[]).length;
-        }
-        return {
-          rows: result as Record<string, unknown>[],
-          affectedRows,
-        };
-      },
-
-      async transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>, options?: TransactionOptions): Promise<T> {
-        return parentMode === "pool"
-          ? txViaPool(fn, options)
-          : txViaSavepoint(fn);
-      },
-
-      async connect() {
-        // Only the pool-level adapter can reserve a fresh connection.
-        // Adapters scoped to a reserved/tx connection are already connected.
-        if (parentMode === "pool") {
-          const reserved = await (sql as SqlInstance).reserve();
-          reserved.release();
-        }
-      },
-
-      async disconnect() {
-        if (parentMode === "pool") {
-          await (sql as SqlInstance).close();
-          sqlInstance = null;
-        }
-        // Inside a transaction `.disconnect()` is a no-op — the pool owns
-        // the connection lifecycle.
-      },
-
-      formatArrayParam(values: unknown[]): unknown {
-        return toPgArrayLiteral(values);
-      },
-    };
-  }
-
-  // Create a lazy adapter that initializes the SQL connection on first use.
-  // Each top-level call lazily resolves the underlying `SqlInstance`. The
-  // `savepointCounter` for every top-level transaction is freshly created
-  // inside that transaction's own `txViaPool` / `txViaSavepoint` — at the
-  // pool level there's no shared counter to manage.
-  function poolAdapter(): DatabaseAdapter {
-    return createAdapter({
-      sql: getSql(),
-      parentMode: "pool",
-      savepointCounter: { n: 0 },
-    });
-  }
-
-  const adapter: DatabaseAdapter = {
-    async execute(params) {
-      return poolAdapter().execute(params);
-    },
-
-    async executeUnsafe(params) {
-      return poolAdapter().executeUnsafe(params);
-    },
-
-    async transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>, options?: TransactionOptions): Promise<T> {
-      return poolAdapter().transaction(fn, options);
-    },
-
-    async connect() {
-      return poolAdapter().connect();
-    },
-
-    async disconnect() {
-      if (sqlInstance) {
-        await sqlInstance.close();
-        sqlInstance = null;
-      }
-    },
-
-    formatArrayParam(values: unknown[]): unknown {
-      return toPgArrayLiteral(values);
-    },
-  };
-
-  return adapter;
-}