@nextlyhq/adapter-sqlite 0.0.2-alpha.68 → 0.0.2-alpha.69

package/dist/index.mjs

@@ -1,860 +1,892 @@
-import { AsyncLocalStorage, AsyncResource } from 'async_hooks';
-import { DrizzleAdapter } from '@nextlyhq/adapter-drizzle';
-import { isApplicationError, createDatabaseError, isDatabaseError } from '@nextlyhq/adapter-drizzle/types';
-import { checkDialectVersion } from '@nextlyhq/adapter-drizzle/version-check';
-import { drizzle } from 'drizzle-orm/better-sqlite3';
-import { getTableConfig } from 'drizzle-orm/sqlite-core';
-
+import { AsyncLocalStorage, AsyncResource } from "node:async_hooks";
+import { DrizzleAdapter } from "@nextlyhq/adapter-drizzle";
+import { createDatabaseError, isApplicationError, isDatabaseError, poolWaitTimeoutError } from "@nextlyhq/adapter-drizzle/types";
+import { checkDialectVersion } from "@nextlyhq/adapter-drizzle/version-check";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { getTableConfig } from "drizzle-orm/sqlite-core";
 // src/index.ts
-var VERSION = "0.1.0";
-var SQLITE_ERROR_CODES = {
-  // Constraint violations
-  SQLITE_CONSTRAINT: "constraint",
-  SQLITE_CONSTRAINT_UNIQUE: "unique_violation",
-  SQLITE_CONSTRAINT_PRIMARYKEY: "unique_violation",
-  SQLITE_CONSTRAINT_FOREIGNKEY: "foreign_key_violation",
-  SQLITE_CONSTRAINT_NOTNULL: "not_null_violation",
-  SQLITE_CONSTRAINT_CHECK: "check_violation",
-  // Busy/locked errors
-  SQLITE_BUSY: "timeout",
-  SQLITE_LOCKED: "timeout",
-  // Connection errors
-  SQLITE_CANTOPEN: "connection",
-  SQLITE_NOTADB: "connection",
-  SQLITE_CORRUPT: "connection",
-  // Query errors
-  SQLITE_ERROR: "query",
-  SQLITE_MISUSE: "query",
-  SQLITE_RANGE: "query"
+/**
+* @nextlyhq/adapter-sqlite
+*
+* SQLite database adapter for Nextly.
+* Extends DrizzleAdapter from @nextlyhq/adapter-drizzle to provide SQLite-specific functionality.
+*
+* @remarks
+* This adapter uses the better-sqlite3 package for database connectivity and provides:
+* - Synchronous API wrapped for async interface compatibility
+* - Transactions the adapter runs itself (BEGIN IMMEDIATE / COMMIT / ROLLBACK), with nested calls run as savepoints
+* - CRUD operations with RETURNING clause support (SQLite 3.35+)
+* - WAL mode for better concurrent read performance
+* - In-memory and file-based database support
+*
+* @example
+* ```typescript
+* import { createSqliteAdapter } from '@nextlyhq/adapter-sqlite';
+*
+* const adapter = createSqliteAdapter({
+*   url: 'file:./data/app.db',
+* });
+*
+* await adapter.connect();
+*
+* // Query data
+* const users = await adapter.select('users', {
+*   where: { and: [{ column: 'status', op: '=', value: 'active' }] },
+*   limit: 10,
+* });
+*
+* await adapter.disconnect();
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* Package version
+*/
+const VERSION = "0.1.0";
+/**
+* SQLite error codes mapping to DatabaseErrorKind.
+*
+* @see https://sqlite.org/rescode.html
+*/
+const SQLITE_ERROR_CODES = {
+	SQLITE_CONSTRAINT: "constraint",
+	SQLITE_CONSTRAINT_UNIQUE: "unique_violation",
+	SQLITE_CONSTRAINT_PRIMARYKEY: "unique_violation",
+	SQLITE_CONSTRAINT_FOREIGNKEY: "foreign_key_violation",
+	SQLITE_CONSTRAINT_NOTNULL: "not_null_violation",
+	SQLITE_CONSTRAINT_CHECK: "check_violation",
+	SQLITE_BUSY: "timeout",
+	SQLITE_LOCKED: "timeout",
+	SQLITE_CANTOPEN: "connection",
+	SQLITE_NOTADB: "connection",
+	SQLITE_CORRUPT: "connection",
+	SQLITE_ERROR: "query",
+	SQLITE_MISUSE: "query",
+	SQLITE_RANGE: "query"
 };
-var DEFAULT_CONFIG = {
-  busyTimeout: 5e3,
-  wal: true,
-  foreignKeys: true
+/**
+* Default configuration values.
+*/
+const DEFAULT_CONFIG = {
+	busyTimeout: 5e3,
+	wal: true,
+	foreignKeys: true,
+	connectionTimeoutMs: 15e3
 };
+/**
+* Converts a JavaScript value to a type that better-sqlite3 can bind.
+* better-sqlite3 only accepts: number, string, bigint, Buffer, null.
+*
+* These conversions have to match what the schema declares, because the rows
+* they write are read back through it. Every column here that takes a `Date`
+* is `integer({ mode: "timestamp" })` — the system columns and user date
+* fields in `runtime-schema-generator.ts`, and the core tables, whose date
+* columns are all INTEGER. So a date is bound as unix seconds, which is what
+* that mode reads.
+*/
 function sanitizeSqliteValue(v) {
-  if (v === void 0) return null;
-  if (typeof v === "boolean") return v ? 1 : 0;
-  if (Buffer.isBuffer(v) || ArrayBuffer.isView(v)) return v;
-  if (v instanceof Date) return Math.floor(v.getTime() / 1e3);
-  if (v !== null && typeof v === "object") return JSON.stringify(v);
-  return v;
+	if (v === void 0) return null;
+	if (typeof v === "boolean") return v ? 1 : 0;
+	if (Buffer.isBuffer(v) || ArrayBuffer.isView(v)) return v;
+	if (v instanceof Date) return Math.floor(v.getTime() / 1e3);
+	if (v !== null && typeof v === "object") return JSON.stringify(v);
+	return v;
 }
+/**
+* SQLite database adapter for Nextly.
+*
+* Extends the base DrizzleAdapter to provide SQLite-specific functionality
+* using the better-sqlite3 package.
+*
+* @remarks
+* SQLite has some differences from PostgreSQL:
+* - Synchronous API (wrapped for async compatibility)
+* - No connection pooling (single file/connection)
+* - RETURNING clause supported (SQLite 3.35+)
+* - Savepoints supported via nested transactions
+* - No native ILIKE (uses LOWER() LIKE workaround)
+* - JSON support (not JSONB)
+* - No array types
+*
+* @example
+* ```typescript
+* const adapter = new SqliteAdapter({
+*   url: 'file:./data.db',
+* });
+*
+* await adapter.connect();
+* ```
+*/
 var SqliteAdapter = class extends DrizzleAdapter {
-  // getDrizzle memoization: drizzle v1's constructor builds a relational
-  // query builder per table in the relations config (~40 tables), and the
-  // service layer resolves an instance on every db access — construct once
-  // per relations object (identity-stable: the schema registry caches it
-  // and hands out a NEW object on invalidation, which naturally misses
-  // this cache and produces a fresh instance).
-  drizzleByRelations = /* @__PURE__ */ new WeakMap();
-  drizzleBare;
-  /**
-   * The database dialect - always 'sqlite' for this adapter.
-   */
-  dialect = "sqlite";
-  /**
-   * Adapter configuration.
-   */
-  config;
-  /**
-   * better-sqlite3 Database instance.
-   */
-  db = null;
-  /**
-   * Connection state flag.
-   */
-  connected = false;
-  /**
-   * Serialization queue for concurrent `transaction()` calls.
-   *
-   * better-sqlite3 is synchronous, single-connection, and rejects nested
-   * `BEGIN` with "cannot start a transaction within a transaction".
-   * When two `await adapter.transaction(...)` calls overlap (e.g. a bulk
-   * mutation calling `Promise.allSettled` with N per-row updates), the
-   * second one tries to BEGIN while the first is still open and the
-   * driver throws.
-   *
-   * Postgres/MySQL avoid this by allocating a fresh client/connection
-   * per transaction from a pool — there is no equivalent for
-   * better-sqlite3, so we serialize at the JS layer instead. Every
-   * `transaction()` invocation chains onto this promise; only one
-   * BEGIN→COMMIT/ROLLBACK section runs at any moment, preserving
-   * write-isolation semantics that callers expect from a transactional
-   * adapter.
-   *
-   * Performance impact is the natural floor: SQLite already serializes
-   * writers at the file-lock level, so the queue removes failed-call
-   * surface area without changing the achievable concurrency.
-   */
-  transactionQueue = Promise.resolve();
-  /**
-   * The transaction the current async chain is running inside, if any.
-   *
-   * A `transaction()` call made from INSIDE a transaction's work — a store
-   * writing on behalf of the caller, a plugin's write inside its own
-   * `ctx.db.transaction` — used to queue behind the very transaction that
-   * was waiting for it, and neither ever settled: that hung every later
-   * transaction on the instance too. Such a call now runs as a SAVEPOINT of
-   * the active transaction instead, so it commits or rolls back with it and
-   * its own failure undoes only its own part.
-   */
-  transactionScope = new AsyncLocalStorage();
-  /**
-   * Creates a new SQLite adapter instance.
-   *
-   * @param config - Adapter configuration
-   */
-  constructor(config) {
-    super();
-    this.config = config;
-  }
-  /**
-   * Connect to the SQLite database.
-   *
-   * @remarks
-   * This method initializes the database connection. For SQLite, this
-   * opens the database file or creates an in-memory database.
-   * Also configures WAL mode and foreign keys based on config.
-   *
-   * @throws {DatabaseError} If connection fails
-   */
-  async connect() {
-    if (this.connected && this.db) {
-      return;
-    }
-    try {
-      const BetterSqlite3 = await import('better-sqlite3');
-      const Database = BetterSqlite3.default;
-      let dbPath;
-      if (this.config.memory) {
-        dbPath = ":memory:";
-      } else if (this.config.url) {
-        dbPath = this.config.url.replace(/^file:/, "");
-      } else {
-        dbPath = ":memory:";
-      }
-      if (dbPath !== ":memory:" && !this.config.readonly) {
-        const fs = await import('fs');
-        const path = await import('path');
-        const dir = path.dirname(path.resolve(dbPath));
-        await fs.promises.mkdir(dir, { recursive: true });
-      }
-      this.db = new Database(dbPath, {
-        readonly: this.config.readonly ?? false,
-        timeout: this.config.busyTimeout ?? DEFAULT_CONFIG.busyTimeout
-      });
-      if ((this.config.wal ?? DEFAULT_CONFIG.wal) && dbPath !== ":memory:" && !this.config.readonly) {
-        this.db.pragma("journal_mode = WAL");
-      }
-      if (this.config.foreignKeys ?? DEFAULT_CONFIG.foreignKeys) {
-        this.db.pragma("foreign_keys = ON");
-      }
-      await checkDialectVersion(this.db, "sqlite");
-      this.connected = true;
-      if (this.config.logger?.info) {
-        this.config.logger.info("SQLite connection established", {
-          url: dbPath === ":memory:" ? "in-memory" : dbPath,
-          wal: this.config.wal ?? DEFAULT_CONFIG.wal,
-          foreignKeys: this.config.foreignKeys ?? DEFAULT_CONFIG.foreignKeys
-        });
-      }
-    } catch (error) {
-      if (this.db) {
-        try {
-          this.db.close();
-        } catch {
-        }
-        this.db = null;
-      }
-      throw this.classifyError(error);
-    }
-  }
-  /**
-   * Disconnect from the SQLite database.
-   *
-   * @remarks
-   * This method closes the database connection and releases resources.
-   */
-  // better-sqlite3 is synchronous; method is async to satisfy the DatabaseAdapter contract.
-  // eslint-disable-next-line @typescript-eslint/require-await
-  async disconnect() {
-    this.drizzleBare = void 0;
-    this.drizzleByRelations = /* @__PURE__ */ new WeakMap();
-    if (!this.db) {
-      return;
-    }
-    try {
-      this.db.close();
-      if (this.config.logger?.info) {
-        this.config.logger.info("SQLite connection closed");
-      }
-    } finally {
-      this.db = null;
-      this.connected = false;
-    }
-  }
-  /**
-   * Check if connected to the database.
-   */
-  isConnected() {
-    return this.connected && this.db !== null;
-  }
-  /**
-   * Get connection pool statistics.
-   *
-   * @remarks
-   * SQLite doesn't use connection pooling, so this returns null.
-   * The database is single-file with a single connection.
-   */
-  getPoolStats() {
-    return null;
-  }
-  /**
-   * Execute a raw SQL query.
-   *
-   * @param sql - SQL query string with $1, $2 placeholders (converted to ? for SQLite)
-   * @param params - Query parameters
-   * @returns Query results
-   *
-   * @throws {DatabaseError} If query execution fails
-   */
-  // better-sqlite3 is synchronous; method is async to satisfy the DatabaseAdapter contract.
-  // eslint-disable-next-line @typescript-eslint/require-await
-  async executeQuery(sql, params = []) {
-    const db = this.ensureDb();
-    const startTime = Date.now();
-    try {
-      const convertedSql = this.convertPlaceholders(sql);
-      const trimmedSql = convertedSql.trim().toUpperCase();
-      const isPragmaQuery = trimmedSql.startsWith("PRAGMA") && !trimmedSql.includes("=");
-      const isSelect = trimmedSql.startsWith("SELECT") || isPragmaQuery || trimmedSql.startsWith("WITH");
-      const hasReturning = trimmedSql.includes("RETURNING");
-      let result;
-      const sanitizedParams = params.map(sanitizeSqliteValue);
-      if (isSelect || hasReturning) {
-        const stmt = db.prepare(convertedSql);
-        result = stmt.all(...sanitizedParams);
-      } else {
-        const stmt = db.prepare(convertedSql);
-        const runResult = stmt.run(...sanitizedParams);
-        result = [
-          {
-            changes: runResult.changes,
-            lastInsertRowid: runResult.lastInsertRowid
-          }
-        ];
-      }
-      if (this.config.logger?.query) {
-        const durationMs = Date.now() - startTime;
-        this.config.logger.query(convertedSql, params, durationMs);
-      }
-      return result;
-    } catch (error) {
-      throw this.classifyError(error, sql);
-    }
-  }
-  /**
-   * Execute work within a transaction.
-   *
-   * @param work - Function containing transactional operations
-   * @param options - Transaction options (isolation level not fully supported in SQLite)
-   * @returns Result of the work function
-   *
-   * @remarks
-   * The adapter manages the transaction itself, because better-sqlite3's
-   * `db.transaction()` does not take async work: it runs `BEGIN IMMEDIATE`,
-   * then `COMMIT` when `work` resolves or `ROLLBACK` when it throws.
-   * - Top-level calls run one at a time.
-   * - A call made inside an open transaction's work joins it as a savepoint
-   *   (`SAVEPOINT` / `RELEASE` / `ROLLBACK TO`).
-   * - Nested calls of one scope run one at a time.
-   * - A call made later from a savepoint that has already released joins the
-   *   innermost scope still open.
-   * - Nested work started and not awaited finishes before the enclosing scope
-   *   commits or rolls back.
-   *
-   * Note: SQLite uses DEFERRED, IMMEDIATE, or EXCLUSIVE transaction modes
-   * rather than isolation levels. This adapter uses IMMEDIATE.
-   */
-  async transaction(work, _options) {
-    const own = this.transactionScope.getStore();
-    const parent = this.nestingScope();
-    if (own && parent !== own) own.writesAfterClosing += 1;
-    if (parent) {
-      return enqueueIn(parent, () => this.runSavepoint(work, parent));
-    }
-    const run = async () => this.runTransaction(work);
-    const next = this.transactionQueue.then(run, run);
-    this.transactionQueue = next.catch(() => void 0);
-    const { result, effects } = await next;
-    await this.runHeldEffects(effects);
-    return result;
-  }
-  /**
-   * Hold `effect` until the transaction enclosing this async context commits,
-   * or run it now when none does.
-   *
-   * The effect belongs to the scope this async context runs in, even one
-   * that has already released or rolled back: a service whose own
-   * transaction nested as a savepoint registers from its caller's scope once
-   * that savepoint has released, and the change is undoable for as long as
-   * any scope around it is. The outermost transaction runs the effect once
-   * its COMMIT succeeds, unless a scope between the effect's scope and the
-   * outermost transaction rolled back, and drops every effect on ROLLBACK or
-   * a failed COMMIT. A context whose outermost transaction has already
-   * finished is outside any transaction, so its effect runs now, unless what
-   * it announces was undone and it has run no transaction since.
-   */
-  async afterCommit(effect, onDeferredFailure) {
-    const scope = this.transactionScope.getStore();
-    if (!scope) {
-      await effect();
-      return;
-    }
-    const root = outermost(scope);
-    if (!root.finished) {
-      root.held.push({
-        effect: this.inRegisteringContext(effect),
-        onDeferredFailure,
-        scope,
-        writesBefore: scope.writesAfterClosing
-      });
-      return;
-    }
-    if (!undone(scope, scope.writesAfterClosing)) await effect();
-  }
-  /**
-   * `effect`, bound to the async context it is registered from.
-   *
-   * A held effect runs after the outermost COMMIT, from the code that ran the
-   * outermost transaction, so without this it sees that code's context rather
-   * than its own: whatever its caller pinned around the write is gone. That
-   * includes who is calling. A scope pinned for a scoped API key lost there
-   * leaves a hook's nested call judged by the key's owner instead of the key,
-   * and a person's frame lost there leaves the hook told of nobody.
-   *
-   * The adapter's own transaction scope is the one store it leaves: the
-   * effect runs once that transaction has finished, outside it, as an effect
-   * held to the outermost commit always has.
-   */
-  inRegisteringContext(effect) {
-    return AsyncResource.bind(() => this.transactionScope.exit(effect));
-  }
-  /**
-   * Run the effects a committed transaction held, in order. A failure is
-   * reported, never thrown: the change is durable, and reporting the
-   * transaction as failed would invite a retry of something already done.
-   */
-  async runHeldEffects(effects) {
-    for (const { effect, onDeferredFailure } of effects) {
-      try {
-        await effect();
-      } catch (error) {
-        this.reportHeldEffectFailure(error, onDeferredFailure);
-      }
-    }
-  }
-  /** Hand a held effect's failure to its reporter, or to the adapter's log. */
-  reportHeldEffectFailure(error, onDeferredFailure) {
-    try {
-      if (onDeferredFailure) {
-        onDeferredFailure(error);
-        return;
-      }
-    } catch {
-    }
-    const failure = error instanceof Error ? error : new Error(String(error));
-    if (this.config.logger?.error) {
-      this.config.logger.error(failure, { phase: "after-commit" });
-    } else {
-      console.error("An effect held until commit failed:", failure);
-    }
-  }
-  /**
-   * Whether a `transaction()` call made here would join an open transaction
-   * as a savepoint. On SQLite it would: the connection is the only one, so a
-   * transaction open on it encloses whatever the async chain that opened it
-   * starts.
-   */
-  inTransaction() {
-    return this.nestingScope() !== void 0;
-  }
-  /**
-   * Whether the calling async flow is inside a transaction that has not
-   * finished, judged from the transaction this flow was started inside,
-   * never from the connection: another request's open transaction answers
-   * false here, where its own `transaction()` queues behind that one.
-   *
-   * A flow started inside a transaction, even inside a savepoint that has
-   * since released, stays inside it until its outermost transaction has
-   * committed or rolled back: until then whatever it writes on the one
-   * connection lands in that transaction.
-   */
-  transactionOpenInFlow() {
-    const own = this.transactionScope.getStore();
-    return own !== void 0 && !outermost(own).finished;
-  }
-  /**
-   * The scope a `transaction()` call made here nests in, or none when it
-   * opens a transaction of its own.
-   *
-   * A call made later from inside a savepoint that has since released runs
-   * inside the innermost scope open on the connection. Queued on an enclosing
-   * scope, or on the instance, it would wait behind the scope running there,
-   * which may be the one awaiting it. Savepoints on one connection form a
-   * stack, so whatever opens now is inside that innermost scope anyway; when
-   * none is open the call queues on the instance.
-   *
-   * The innermost open scope need not be related to the call. When it is a
-   * sibling savepoint that later rolls back, the call's write rolls back with
-   * it, although the call itself already resolved. Waiting for an unrelated
-   * scope instead could wait on the very scope that awaits the call.
-   */
-  nestingScope() {
-    const own = this.transactionScope.getStore();
-    return own?.active ? own : own?.open.at(-1);
-  }
-  /**
-   * Run `work` as a savepoint of the active transaction: released when it
-   * resolves, rolled back to when it throws.
-   */
-  async runSavepoint(work, parent) {
-    const db = this.ensureDb();
-    const depth = parent.depth + 1;
-    const name = `nextly_sp_${depth}`;
-    try {
-      const ctx = this.createTransactionContext(db);
-      db.exec(`SAVEPOINT ${name}`);
-      const scope = openScope(parent);
-      try {
-        const result = await this.transactionScope.run(scope, () => work(ctx));
-        await settleNested(scope);
-        db.exec(`RELEASE ${name}`);
-        return result;
-      } catch (error) {
-        await settleNested(scope);
-        scope.rolledBack = true;
-        try {
-          db.exec(`ROLLBACK TO ${name}`);
-          db.exec(`RELEASE ${name}`);
-        } catch {
-        }
-        throw error;
-      }
-    } catch (error) {
-      if (isApplicationError(error)) throw error;
-      throw this.classifyError(error);
-    }
-  }
-  /**
-   * Inner transaction body. Kept private so callers always go through
-   * the serialized `transaction()` queue above and the BEGIN/COMMIT
-   * pair is never invoked outside of it.
-   */
-  async runTransaction(work) {
-    const db = this.ensureDb();
-    const startTime = Date.now();
-    try {
-      const ctx = this.createTransactionContext(db);
-      db.exec("BEGIN IMMEDIATE");
-      const scope = openScope();
-      try {
-        const result = await this.transactionScope.run(scope, () => work(ctx));
-        await settleNested(scope);
-        db.exec("COMMIT");
-        scope.finished = true;
-        if (this.config.logger?.debug) {
-          const durationMs = Date.now() - startTime;
-          this.config.logger.debug("Transaction committed", {
-            durationMs
-          });
-        }
-        return {
-          result,
-          effects: scope.held.filter(
-            (held) => !undone(held.scope, held.writesBefore)
-          )
-        };
-      } catch (error) {
-        await settleNested(scope);
-        scope.rolledBack = true;
-        scope.finished = true;
-        scope.held.length = 0;
-        try {
-          db.exec("ROLLBACK");
-        } catch {
-        }
-        throw error;
-      }
-    } catch (error) {
-      if (isApplicationError(error)) throw error;
-      throw this.classifyError(error);
-    }
-  }
-  /**
-   * Get SQLite database capabilities.
-   *
-   * @remarks
-   * SQLite capabilities:
-   * - JSON support (not JSONB)
-   * - No arrays
-   * - No native ILIKE
-   * - RETURNING clause (3.35+)
-   * - Savepoints supported
-   * - ON CONFLICT supported
-   */
-  getCapabilities() {
-    return {
-      dialect: "sqlite",
-      supportsJsonb: false,
-      // SQLite uses JSON, not JSONB
-      supportsJson: true,
-      supportsArrays: false,
-      // SQLite doesn't support array types
-      supportsGeneratedColumns: true,
-      // SQLite 3.31+
-      supportsFts: true,
-      // SQLite FTS5
-      supportsIlike: false,
-      // No native ILIKE, use LOWER() LIKE
-      supportsReturning: true,
-      // SQLite 3.35+
-      supportsSavepoints: true,
-      // SQLite supports savepoints
-      supportsOnConflict: true,
-      // ON CONFLICT clause
-      maxParamsPerQuery: 999,
-      // SQLite SQLITE_MAX_VARIABLE_NUMBER default
-      maxIdentifierLength: 128
-      // SQLite doesn't have a strict limit
-    };
-  }
-  /**
-   * Override insertMany for bulk insert optimization.
-   *
-   * @remarks
-   * Uses a single multi-row INSERT statement for better performance.
-   */
-  async insertMany(table, data, options) {
-    if (data.length === 0) {
-      return [];
-    }
-    const db = this.ensureDb();
-    if (data.length === 1) {
-      const result = await this.insert(table, data[0], options);
-      return [result];
-    }
-    const columns = Object.keys(data[0]);
-    const params = [];
-    const valuesClauses = [];
-    for (const record of data) {
-      const placeholders = [];
-      for (const col of columns) {
-        params.push(sanitizeSqliteValue(record[col]));
-        placeholders.push("?");
-      }
-      valuesClauses.push(`(${placeholders.join(", ")})`);
-    }
-    const columnList = columns.map((col) => this.escapeIdentifier(col)).join(", ");
-    let sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columnList}) VALUES ${valuesClauses.join(", ")}`;
-    if (options?.returning) {
-      const returning = options.returning === "*" ? "*" : options.returning.map((col) => this.escapeIdentifier(col)).join(", ");
-      sql += ` RETURNING ${returning}`;
-    } else {
-      sql += " RETURNING *";
-    }
-    try {
-      const stmt = db.prepare(sql);
-      const rows = stmt.all(...params);
-      const tableObj = this.getTableObject(table);
-      return rows.map((r) => this.mapRowFromRawSql(tableObj, r));
-    } catch (error) {
-      throw this.handleQueryError(error, "insertMany", table);
-    }
-  }
-  // ============================================================
-  // Protected Helper Methods
-  // ============================================================
-  /**
-   * Ensures database is connected and returns it.
-   *
-   * @throws {DatabaseError} If not connected
-   */
-  ensureDb() {
-    if (!this.db) {
-      throw createDatabaseError({
-        kind: "connection",
-        message: "SqliteAdapter is not connected. Call connect() first."
-      });
-    }
-    return this.db;
-  }
-  /**
-   * Return the typed Drizzle instance for SQLite.
-   * Guarded for server-only usage and requires an active connection.
-   *
-   * @param schema - Optional schema for relational queries (db.query.*)
-   * @returns Drizzle ORM instance wrapping the better-sqlite3 connection
-   * @throws {Error} If called in browser or not connected
-   */
-  getDrizzle(relations) {
-    if (typeof window !== "undefined") {
-      throw new Error("getDrizzle() is server-only");
-    }
-    const db = this.ensureDb();
-    if (!relations) {
-      this.drizzleBare ??= drizzle({ client: db });
-      return this.drizzleBare;
-    }
-    let cached = this.drizzleByRelations.get(relations);
-    if (!cached) {
-      cached = drizzle({ client: db, relations });
-      this.drizzleByRelations.set(relations, cached);
-    }
-    return cached;
-  }
-  /**
-   * Convert $1, $2 placeholders to ? for better-sqlite3.
-   *
-   * @param sql - SQL with PostgreSQL-style placeholders
-   * @returns SQL with ? placeholders
-   */
-  convertPlaceholders(sql) {
-    return sql.replace(/\$\d+/g, "?");
-  }
-  /**
-   * Creates a TransactionContext for the given database connection.
-   */
-  /** A table-level `primaryKey({ columns })`, read through the SQLite table config. */
-  compositePrimaryKey(tableObj) {
-    return getTableConfig(
-      tableObj
-    ).primaryKeys.flatMap((key) => key.columns);
-  }
-  createTransactionContext(db) {
-    const txHandles = this.transactionDrizzleHandles(
-      (relations) => relations ? drizzle({ client: db, relations }) : drizzle({ client: db })
-    );
-    const txDb = txHandles.bare;
-    return {
-      drizzleWithRelations: txHandles.withRelations,
-      // SQLite has no row-level locking and needs none here: `withTransaction`
-      // opens SQLite transactions with BEGIN IMMEDIATE, which takes the write
-      // lock up front and serializes writers for the whole transaction.
-      lockRow: () => Promise.resolve(),
-      // `run`, not `all`: better-sqlite3 throws on a statement that returns no
-      // rows, which is every statement this method exists to carry. The Drizzle
-      // instance is the transaction-bound one, so the statement runs inside this
-      // transaction.
-      //
-      // better-sqlite3 is synchronous, so this resolves an already-settled
-      // promise rather than being declared `async` over a body that never
-      // awaits.
-      runStatement: (statement) => {
-        txDb().run(statement);
-        return Promise.resolve();
-      },
-      // `all`, not `run`: this is the reading half, and better-sqlite3 returns
-      // rows only from `all`. Synchronous, so the promise is already settled.
-      queryStatement: (statement) => Promise.resolve(txDb().all(statement)),
-      // eslint-disable-next-line @typescript-eslint/require-await
-      execute: async (sql, params = []) => {
-        const convertedSql = this.convertPlaceholders(sql);
-        const trimmedSql = convertedSql.trim().toUpperCase();
-        const isSelect = trimmedSql.startsWith("SELECT") || trimmedSql.includes("RETURNING");
-        const sanitizedParams = params.map(sanitizeSqliteValue);
-        if (isSelect) {
-          const stmt = db.prepare(convertedSql);
-          return stmt.all(...sanitizedParams);
-        } else {
-          const stmt = db.prepare(convertedSql);
-          const result = stmt.run(...sanitizedParams);
-          return [
-            {
-              changes: result.changes,
-              lastInsertRowid: result.lastInsertRowid
-            }
-          ];
-        }
-      },
-      // Keys only, unlike the PostgreSQL and MySQL raw paths, which also encode
-      // their date values. `sanitizeSqliteValue` below binds a `Date` as unix
-      // seconds, and an instant carries no zone -- so what SQLite stores does
-      // not depend on the server's timezone and there is nothing to correct.
-      // eslint-disable-next-line @typescript-eslint/require-await
-      insert: async (table, data, options) => {
-        const mapped = this.mapKeysToSqlColumns(
-          this.getTableObject(table),
-          data
-        );
-        const columns = Object.keys(mapped);
-        const values = Object.values(mapped).map(sanitizeSqliteValue);
-        const placeholders = values.map(() => "?").join(", ");
-        let sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columns.map((c) => this.escapeIdentifier(c)).join(", ")}) VALUES (${placeholders})`;
-        const ret = options?.returning;
-        const returningEmpty = Array.isArray(ret) && ret.length === 0;
-        if (!returningEmpty) {
-          const returning = !ret || ret === "*" ? "*" : this.mapColumnNamesToSql(this.getTableObject(table), ret).map((col) => this.escapeIdentifier(col)).join(", ");
-          sql += ` RETURNING ${returning}`;
-        }
-        const stmt = db.prepare(sql);
-        if (returningEmpty) {
-          stmt.run(...values);
-          return void 0;
-        }
-        const rows = stmt.all(...values);
-        return this.mapRowFromRawSql(this.getTableObject(table), rows[0]);
-      },
-      // eslint-disable-next-line @typescript-eslint/require-await
-      insertMany: async (table, data, options) => {
-        if (data.length === 0) return [];
-        const tableObj = this.getTableObject(table);
-        const mappedRecords = data.map(
-          (r) => this.mapKeysToSqlColumns(tableObj, r)
-        );
-        const columns = Object.keys(mappedRecords[0]);
-        const allValues = [];
-        const valuesClauses = [];
-        for (const record of mappedRecords) {
-          const placeholders = [];
-          for (const col of columns) {
-            allValues.push(sanitizeSqliteValue(record[col]));
-            placeholders.push("?");
-          }
-          valuesClauses.push(`(${placeholders.join(", ")})`);
-        }
-        let sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columns.map((c) => this.escapeIdentifier(c)).join(", ")}) VALUES ${valuesClauses.join(", ")}`;
-        const ret = options?.returning;
-        const returningEmpty = Array.isArray(ret) && ret.length === 0;
-        if (!returningEmpty) {
-          const returning = !ret || ret === "*" ? "*" : this.mapColumnNamesToSql(this.getTableObject(table), ret).map((col) => this.escapeIdentifier(col)).join(", ");
-          sql += ` RETURNING ${returning}`;
-        }
-        const stmt = db.prepare(sql);
-        if (returningEmpty) {
-          stmt.run(...allValues);
-          return [];
-        }
-        return stmt.all(...allValues).map(
-          (r) => this.mapRowFromRawSql(tableObj, r)
-        );
-      },
-      // Adapter-built, as `insert` above is; `transactionUpdate` says why.
-      // A column the model does not declare binds as every other value on
-      // this path does, through `sanitizeSqliteValue`. `all` only when the
-      // statement carries RETURNING: better-sqlite3 throws on `all` for a
-      // statement that returns no rows, and on `run` for one that does.
-      update: this.transactionUpdate(
-        txDb,
-        (statement, returnsRows) => returnsRows ? txDb().all(statement) : (txDb().run(statement), void 0),
-        sanitizeSqliteValue
-      ),
-      ...this.createTransactionForwarders(txDb),
-      // eslint-disable-next-line @typescript-eslint/require-await
-      savepoint: async (name) => {
-        db.exec(`SAVEPOINT ${this.escapeIdentifier(name)}`);
-      },
-      // eslint-disable-next-line @typescript-eslint/require-await
-      rollbackToSavepoint: async (name) => {
-        db.exec(`ROLLBACK TO SAVEPOINT ${this.escapeIdentifier(name)}`);
-      },
-      // eslint-disable-next-line @typescript-eslint/require-await
-      releaseSavepoint: async (name) => {
-        db.exec(`RELEASE SAVEPOINT ${this.escapeIdentifier(name)}`);
-      }
-    };
-  }
-  /**
-   * Classifies a SQLite error into a DatabaseError.
-   *
-   * @param error - Original error from better-sqlite3
-   * @param sql - SQL statement that caused the error (optional)
-   * @returns DatabaseError with proper classification
-   */
-  // fallow-ignore-next-line complexity
-  classifyError(error, sql) {
-    if (isDatabaseError(error)) return error;
-    const sqliteError = this.driverErrorIn(
-      error,
-      (candidate) => typeof candidate.code === "string" && candidate.code !== ""
-    );
-    let kind = "unknown";
-    if (sqliteError.code) {
-      kind = SQLITE_ERROR_CODES[sqliteError.code] || "unknown";
-    } else if (sqliteError.message) {
-      const msg = sqliteError.message.toUpperCase();
-      if (msg.includes("UNIQUE CONSTRAINT")) {
-        kind = "unique_violation";
-      } else if (msg.includes("FOREIGN KEY CONSTRAINT")) {
-        kind = "foreign_key_violation";
-      } else if (msg.includes("NOT NULL CONSTRAINT")) {
-        kind = "not_null_violation";
-      } else if (msg.includes("CHECK CONSTRAINT")) {
-        kind = "check_violation";
-      } else if (msg.includes("BUSY") || msg.includes("LOCKED")) {
-        kind = "timeout";
-      } else if (msg.includes("SQLITE_CANTOPEN") || msg.includes("UNABLE TO OPEN")) {
-        kind = "connection";
-      }
-    }
-    let message = sqliteError.message ?? String(error);
-    if (sql && kind === "query") {
-      message = `Query failed: ${message}`;
-    }
-    return createDatabaseError({
-      kind,
-      message,
-      code: sqliteError.code,
-      cause: error instanceof Error ? error : void 0
-    });
-  }
+	drizzleByRelations = /* @__PURE__ */ new WeakMap();
+	drizzleBare;
+	/**
+	* The database dialect - always 'sqlite' for this adapter.
+	*/
+	dialect = "sqlite";
+	/**
+	* Adapter configuration.
+	*/
+	config;
+	/**
+	* better-sqlite3 Database instance.
+	*/
+	db = null;
+	/**
+	* Connection state flag.
+	*/
+	connected = false;
+	/**
+	* Serialization queue for concurrent `transaction()` calls.
+	*
+	* better-sqlite3 is synchronous, single-connection, and rejects nested
+	* `BEGIN` with "cannot start a transaction within a transaction".
+	* When two `await adapter.transaction(...)` calls overlap (e.g. a bulk
+	* mutation calling `Promise.allSettled` with N per-row updates), the
+	* second one tries to BEGIN while the first is still open and the
+	* driver throws.
+	*
+	* Postgres/MySQL avoid this by allocating a fresh client/connection
+	* per transaction from a pool — there is no equivalent for
+	* better-sqlite3, so we serialize at the JS layer instead. Every
+	* `transaction()` invocation chains onto this promise; only one
+	* BEGIN→COMMIT/ROLLBACK section runs at any moment, preserving
+	* write-isolation semantics that callers expect from a transactional
+	* adapter.
+	*
+	* Performance impact is the natural floor: SQLite already serializes
+	* writers at the file-lock level, so the queue removes failed-call
+	* surface area without changing the achievable concurrency.
+	*/
+	transactionQueue = Promise.resolve();
+	/**
+	* The transaction the current async chain is running inside, if any.
+	*
+	* A `transaction()` call made from INSIDE a transaction's work — a store
+	* writing on behalf of the caller, a plugin's write inside its own
+	* `ctx.db.transaction` — used to queue behind the very transaction that
+	* was waiting for it, and neither ever settled: that hung every later
+	* transaction on the instance too. Such a call now runs as a SAVEPOINT of
+	* the active transaction instead, so it commits or rolls back with it and
+	* its own failure undoes only its own part.
+	*/
+	transactionScope = new AsyncLocalStorage();
+	/**
+	* Creates a new SQLite adapter instance.
+	*
+	* @param config - Adapter configuration
+	*/
+	constructor(config) {
+		super();
+		this.config = config;
+	}
+	/**
+	* Connect to the SQLite database.
+	*
+	* @remarks
+	* This method initializes the database connection. For SQLite, this
+	* opens the database file or creates an in-memory database.
+	* Also configures WAL mode and foreign keys based on config.
+	*
+	* @throws {DatabaseError} If connection fails
+	*/
+	async connect() {
+		if (this.connected && this.db) return;
+		try {
+			const Database = (await import("better-sqlite3")).default;
+			let dbPath;
+			if (this.config.memory) dbPath = ":memory:";
+			else if (this.config.url) dbPath = this.config.url.replace(/^file:/, "");
+			else dbPath = ":memory:";
+			if (dbPath !== ":memory:" && !this.config.readonly) {
+				const fs = await import("node:fs");
+				const path = await import("node:path");
+				const dir = path.dirname(path.resolve(dbPath));
+				await fs.promises.mkdir(dir, { recursive: true });
+			}
+			this.db = new Database(dbPath, {
+				readonly: this.config.readonly ?? false,
+				timeout: this.config.busyTimeout ?? DEFAULT_CONFIG.busyTimeout
+			});
+			if ((this.config.wal ?? DEFAULT_CONFIG.wal) && dbPath !== ":memory:" && !this.config.readonly) this.db.pragma("journal_mode = WAL");
+			if (this.config.foreignKeys ?? DEFAULT_CONFIG.foreignKeys) this.db.pragma("foreign_keys = ON");
+			await checkDialectVersion(this.db, "sqlite");
+			this.connected = true;
+			if (this.config.logger?.info) this.config.logger.info("SQLite connection established", {
+				url: dbPath === ":memory:" ? "in-memory" : dbPath,
+				wal: this.config.wal ?? DEFAULT_CONFIG.wal,
+				foreignKeys: this.config.foreignKeys ?? DEFAULT_CONFIG.foreignKeys
+			});
+		} catch (error) {
+			if (this.db) {
+				try {
+					this.db.close();
+				} catch {}
+				this.db = null;
+			}
+			throw this.classifyError(error);
+		}
+	}
+	/**
+	* Disconnect from the SQLite database.
+	*
+	* @remarks
+	* This method closes the database connection and releases resources.
+	*/
+	async disconnect() {
+		this.drizzleBare = void 0;
+		this.drizzleByRelations = /* @__PURE__ */ new WeakMap();
+		if (!this.db) return;
+		try {
+			this.db.close();
+			if (this.config.logger?.info) this.config.logger.info("SQLite connection closed");
+		} finally {
+			this.db = null;
+			this.connected = false;
+		}
+	}
+	/**
+	* Check if connected to the database.
+	*/
+	isConnected() {
+		return this.connected && this.db !== null;
+	}
+	/**
+	* Get connection pool statistics.
+	*
+	* @remarks
+	* SQLite doesn't use connection pooling, so this returns null.
+	* The database is single-file with a single connection.
+	*/
+	getPoolStats() {
+		return null;
+	}
+	/**
+	* Execute a raw SQL query.
+	*
+	* @param sql - SQL query string with $1, $2 placeholders (converted to ? for SQLite)
+	* @param params - Query parameters
+	* @returns Query results
+	*
+	* @throws {DatabaseError} If query execution fails
+	*/
+	async executeQuery(sql, params = []) {
+		const db = this.ensureDb();
+		const startTime = Date.now();
+		try {
+			const convertedSql = this.convertPlaceholders(sql);
+			const trimmedSql = convertedSql.trim().toUpperCase();
+			const isPragmaQuery = trimmedSql.startsWith("PRAGMA") && !trimmedSql.includes("=");
+			const isSelect = trimmedSql.startsWith("SELECT") || isPragmaQuery || trimmedSql.startsWith("WITH");
+			const hasReturning = trimmedSql.includes("RETURNING");
+			let result;
+			const sanitizedParams = params.map(sanitizeSqliteValue);
+			if (isSelect || hasReturning) result = db.prepare(convertedSql).all(...sanitizedParams);
+			else {
+				const runResult = db.prepare(convertedSql).run(...sanitizedParams);
+				result = [{
+					changes: runResult.changes,
+					lastInsertRowid: runResult.lastInsertRowid
+				}];
+			}
+			if (this.config.logger?.query) {
+				const durationMs = Date.now() - startTime;
+				this.config.logger.query(convertedSql, params, durationMs);
+			}
+			return result;
+		} catch (error) {
+			throw this.classifyError(error, sql);
+		}
+	}
+	/**
+	* Execute work within a transaction.
+	*
+	* @param work - Function containing transactional operations
+	* @param options - Transaction options (isolation level not fully supported in SQLite)
+	* @returns Result of the work function
+	*
+	* @remarks
+	* The adapter manages the transaction itself, because better-sqlite3's
+	* `db.transaction()` does not take async work: it runs `BEGIN IMMEDIATE`,
+	* then `COMMIT` when `work` resolves or `ROLLBACK` when it throws.
+	* - Top-level calls run one at a time.
+	* - A call made inside an open transaction's work joins it as a savepoint
+	*   (`SAVEPOINT` / `RELEASE` / `ROLLBACK TO`).
+	* - Nested calls of one scope run one at a time.
+	* - A call made later from a savepoint that has already released joins the
+	*   innermost scope still open.
+	* - Nested work started and not awaited finishes before the enclosing scope
+	*   commits or rolls back.
+	*
+	* Note: SQLite uses DEFERRED, IMMEDIATE, or EXCLUSIVE transaction modes
+	* rather than isolation levels. This adapter uses IMMEDIATE.
+	*/
+	/** How long a transaction waits for the connection: `pool.connectionTimeoutMs`. */
+	transactionWaitMs() {
+		return this.config.pool?.connectionTimeoutMs ?? DEFAULT_CONFIG.connectionTimeoutMs;
+	}
+	async transaction(work, _options) {
+		const own = this.transactionScope.getStore();
+		const parent = this.nestingScope();
+		if (own && parent !== own) own.writesAfterClosing += 1;
+		if (parent) return enqueueIn(parent, () => this.runSavepoint(work, parent));
+		const run = async () => this.runTransaction(work);
+		const previous = this.transactionQueue;
+		const next = waitForTurn(previous, this.transactionWaitMs()).then(run);
+		this.transactionQueue = previous.then(() => next).catch(() => void 0);
+		const { result, effects } = await next;
+		await this.runHeldEffects(effects);
+		return result;
+	}
+	/**
+	* Hold `effect` until the transaction enclosing this async context commits,
+	* or run it now when none does.
+	*
+	* The effect belongs to the scope this async context runs in, even one
+	* that has already released or rolled back: a service whose own
+	* transaction nested as a savepoint registers from its caller's scope once
+	* that savepoint has released, and the change is undoable for as long as
+	* any scope around it is. The outermost transaction runs the effect once
+	* its COMMIT succeeds, unless a scope between the effect's scope and the
+	* outermost transaction rolled back, and drops every effect on ROLLBACK or
+	* a failed COMMIT. A context whose outermost transaction has already
+	* finished is outside any transaction, so its effect runs now, unless what
+	* it announces was undone and it has run no transaction since.
+	*/
+	async afterCommit(effect, onDeferredFailure) {
+		const scope = this.transactionScope.getStore();
+		if (!scope) {
+			await effect();
+			return;
+		}
+		const root = outermost(scope);
+		if (!root.finished) {
+			root.held.push({
+				effect: this.inRegisteringContext(effect),
+				onDeferredFailure,
+				scope,
+				writesBefore: scope.writesAfterClosing
+			});
+			return;
+		}
+		if (!undone(scope, scope.writesAfterClosing)) await effect();
+	}
+	/**
+	* `effect`, bound to the async context it is registered from.
+	*
+	* A held effect runs after the outermost COMMIT, from the code that ran the
+	* outermost transaction, so without this it sees that code's context rather
+	* than its own: whatever its caller pinned around the write is gone. That
+	* includes who is calling. A scope pinned for a scoped API key lost there
+	* leaves a hook's nested call judged by the key's owner instead of the key,
+	* and a person's frame lost there leaves the hook told of nobody.
+	*
+	* The adapter's own transaction scope is the one store it leaves: the
+	* effect runs once that transaction has finished, outside it, as an effect
+	* held to the outermost commit always has.
+	*/
+	inRegisteringContext(effect) {
+		return AsyncResource.bind(() => this.transactionScope.exit(effect));
+	}
+	/**
+	* Run the effects a committed transaction held, in order. A failure is
+	* reported, never thrown: the change is durable, and reporting the
+	* transaction as failed would invite a retry of something already done.
+	*/
+	async runHeldEffects(effects) {
+		for (const { effect, onDeferredFailure } of effects) try {
+			await effect();
+		} catch (error) {
+			this.reportHeldEffectFailure(error, onDeferredFailure);
+		}
+	}
+	/** Hand a held effect's failure to its reporter, or to the adapter's log. */
+	reportHeldEffectFailure(error, onDeferredFailure) {
+		try {
+			if (onDeferredFailure) {
+				onDeferredFailure(error);
+				return;
+			}
+		} catch {}
+		const failure = error instanceof Error ? error : new Error(String(error));
+		if (this.config.logger?.error) this.config.logger.error(failure, { phase: "after-commit" });
+		else console.error("An effect held until commit failed:", failure);
+	}
+	/**
+	* Whether a `transaction()` call made here would join an open transaction
+	* as a savepoint. On SQLite it would: the connection is the only one, so a
+	* transaction open on it encloses whatever the async chain that opened it
+	* starts.
+	*/
+	inTransaction() {
+		return this.nestingScope() !== void 0;
+	}
+	/**
+	* Whether the calling async flow is inside a transaction that has not
+	* finished, judged from the transaction this flow was started inside,
+	* never from the connection: another request's open transaction answers
+	* false here, where its own `transaction()` queues behind that one.
+	*
+	* A flow started inside a transaction, even inside a savepoint that has
+	* since released, stays inside it until its outermost transaction has
+	* committed or rolled back: until then whatever it writes on the one
+	* connection lands in that transaction.
+	*/
+	transactionOpenInFlow() {
+		const own = this.transactionScope.getStore();
+		return own !== void 0 && !outermost(own).finished;
+	}
+	/**
+	* The scope a `transaction()` call made here nests in, or none when it
+	* opens a transaction of its own.
+	*
+	* A call made later from inside a savepoint that has since released runs
+	* inside the innermost scope open on the connection. Queued on an enclosing
+	* scope, or on the instance, it would wait behind the scope running there,
+	* which may be the one awaiting it. Savepoints on one connection form a
+	* stack, so whatever opens now is inside that innermost scope anyway; when
+	* none is open the call queues on the instance.
+	*
+	* The innermost open scope need not be related to the call. When it is a
+	* sibling savepoint that later rolls back, the call's write rolls back with
+	* it, although the call itself already resolved. Waiting for an unrelated
+	* scope instead could wait on the very scope that awaits the call.
+	*/
+	nestingScope() {
+		const own = this.transactionScope.getStore();
+		return own?.active ? own : own?.open.at(-1);
+	}
+	/**
+	* Run `work` as a savepoint of the active transaction: released when it
+	* resolves, rolled back to when it throws.
+	*/
+	async runSavepoint(work, parent) {
+		const db = this.ensureDb();
+		const name = `nextly_sp_${parent.depth + 1}`;
+		try {
+			const ctx = this.createTransactionContext(db);
+			db.exec(`SAVEPOINT ${name}`);
+			const scope = openScope(parent);
+			try {
+				const result = await this.transactionScope.run(scope, () => work(ctx));
+				await settleNested(scope);
+				db.exec(`RELEASE ${name}`);
+				return result;
+			} catch (error) {
+				await settleNested(scope);
+				scope.rolledBack = true;
+				try {
+					db.exec(`ROLLBACK TO ${name}`);
+					db.exec(`RELEASE ${name}`);
+				} catch {}
+				throw error;
+			}
+		} catch (error) {
+			if (isApplicationError(error)) throw error;
+			throw this.classifyError(error);
+		}
+	}
+	/**
+	* Inner transaction body. Kept private so callers always go through
+	* the serialized `transaction()` queue above and the BEGIN/COMMIT
+	* pair is never invoked outside of it.
+	*/
+	async runTransaction(work) {
+		const db = this.ensureDb();
+		const startTime = Date.now();
+		try {
+			const ctx = this.createTransactionContext(db);
+			db.exec("BEGIN IMMEDIATE");
+			const scope = openScope();
+			try {
+				const result = await this.transactionScope.run(scope, () => work(ctx));
+				await settleNested(scope);
+				db.exec("COMMIT");
+				scope.finished = true;
+				if (this.config.logger?.debug) {
+					const durationMs = Date.now() - startTime;
+					this.config.logger.debug("Transaction committed", { durationMs });
+				}
+				return {
+					result,
+					effects: scope.held.filter((held) => !undone(held.scope, held.writesBefore))
+				};
+			} catch (error) {
+				await settleNested(scope);
+				scope.rolledBack = true;
+				scope.finished = true;
+				scope.held.length = 0;
+				try {
+					db.exec("ROLLBACK");
+				} catch {}
+				throw error;
+			}
+		} catch (error) {
+			if (isApplicationError(error)) throw error;
+			throw this.classifyError(error);
+		}
+	}
+	/**
+	* Get SQLite database capabilities.
+	*
+	* @remarks
+	* SQLite capabilities:
+	* - JSON support (not JSONB)
+	* - No arrays
+	* - No native ILIKE
+	* - RETURNING clause (3.35+)
+	* - Savepoints supported
+	* - ON CONFLICT supported
+	*/
+	getCapabilities() {
+		return {
+			dialect: "sqlite",
+			supportsJsonb: false,
+			supportsJson: true,
+			supportsArrays: false,
+			supportsGeneratedColumns: true,
+			supportsFts: true,
+			supportsIlike: false,
+			supportsReturning: true,
+			supportsSavepoints: true,
+			supportsOnConflict: true,
+			maxParamsPerQuery: 999,
+			maxIdentifierLength: 128
+		};
+	}
+	/**
+	* Override insertMany for bulk insert optimization.
+	*
+	* @remarks
+	* Uses a single multi-row INSERT statement for better performance.
+	*/
+	async insertMany(table, data, options) {
+		if (data.length === 0) return [];
+		const db = this.ensureDb();
+		if (data.length === 1) return [await this.insert(table, data[0], options)];
+		const columns = Object.keys(data[0]);
+		const params = [];
+		const valuesClauses = [];
+		for (const record of data) {
+			const placeholders = [];
+			for (const col of columns) {
+				params.push(sanitizeSqliteValue(record[col]));
+				placeholders.push("?");
+			}
+			valuesClauses.push(`(${placeholders.join(", ")})`);
+		}
+		const columnList = columns.map((col) => this.escapeIdentifier(col)).join(", ");
+		let sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columnList}) VALUES ${valuesClauses.join(", ")}`;
+		if (options?.returning) {
+			const returning = options.returning === "*" ? "*" : options.returning.map((col) => this.escapeIdentifier(col)).join(", ");
+			sql += ` RETURNING ${returning}`;
+		} else sql += " RETURNING *";
+		try {
+			const rows = db.prepare(sql).all(...params);
+			const tableObj = this.getTableObject(table);
+			return rows.map((r) => this.mapRowFromRawSql(tableObj, r));
+		} catch (error) {
+			throw this.handleQueryError(error, "insertMany", table);
+		}
+	}
+	/**
+	* Ensures database is connected and returns it.
+	*
+	* @throws {DatabaseError} If not connected
+	*/
+	ensureDb() {
+		if (!this.db) throw createDatabaseError({
+			kind: "connection",
+			message: "SqliteAdapter is not connected. Call connect() first."
+		});
+		return this.db;
+	}
+	/**
+	* Return the typed Drizzle instance for SQLite.
+	* Guarded for server-only usage and requires an active connection.
+	*
+	* @param schema - Optional schema for relational queries (db.query.*)
+	* @returns Drizzle ORM instance wrapping the better-sqlite3 connection
+	* @throws {Error} If called in browser or not connected
+	*/
+	getDrizzle(relations) {
+		if (typeof window !== "undefined") throw new Error("getDrizzle() is server-only");
+		const db = this.ensureDb();
+		if (!relations) {
+			this.drizzleBare ??= drizzle({ client: db });
+			return this.drizzleBare;
+		}
+		let cached = this.drizzleByRelations.get(relations);
+		if (!cached) {
+			cached = drizzle({
+				client: db,
+				relations
+			});
+			this.drizzleByRelations.set(relations, cached);
+		}
+		return cached;
+	}
+	/**
+	* Convert $1, $2 placeholders to ? for better-sqlite3.
+	*
+	* @param sql - SQL with PostgreSQL-style placeholders
+	* @returns SQL with ? placeholders
+	*/
+	convertPlaceholders(sql) {
+		return sql.replace(/\$\d+/g, "?");
+	}
+	/**
+	* Creates a TransactionContext for the given database connection.
+	*/
+	/** A table-level `primaryKey({ columns })`, read through the SQLite table config. */
+	compositePrimaryKey(tableObj) {
+		return getTableConfig(tableObj).primaryKeys.flatMap((key) => key.columns);
+	}
+	createTransactionContext(db) {
+		const txHandles = this.transactionDrizzleHandles((relations) => relations ? drizzle({
+			client: db,
+			relations
+		}) : drizzle({ client: db }));
+		const txDb = txHandles.bare;
+		return {
+			drizzleWithRelations: txHandles.withRelations,
+			lockRow: () => Promise.resolve(),
+			runStatement: (statement) => {
+				txDb().run(statement);
+				return Promise.resolve();
+			},
+			queryStatement: (statement) => Promise.resolve(txDb().all(statement)),
+			execute: async (sql, params = []) => {
+				const convertedSql = this.convertPlaceholders(sql);
+				const trimmedSql = convertedSql.trim().toUpperCase();
+				const isSelect = trimmedSql.startsWith("SELECT") || trimmedSql.includes("RETURNING");
+				const sanitizedParams = params.map(sanitizeSqliteValue);
+				if (isSelect) return db.prepare(convertedSql).all(...sanitizedParams);
+				else {
+					const result = db.prepare(convertedSql).run(...sanitizedParams);
+					return [{
+						changes: result.changes,
+						lastInsertRowid: result.lastInsertRowid
+					}];
+				}
+			},
+			insert: async (table, data, options) => {
+				const mapped = this.mapKeysToSqlColumns(this.getTableObject(table), data);
+				const columns = Object.keys(mapped);
+				const values = Object.values(mapped).map(sanitizeSqliteValue);
+				const placeholders = values.map(() => "?").join(", ");
+				let sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columns.map((c) => this.escapeIdentifier(c)).join(", ")}) VALUES (${placeholders})`;
+				const ret = options?.returning;
+				const returningEmpty = Array.isArray(ret) && ret.length === 0;
+				if (!returningEmpty) {
+					const returning = !ret || ret === "*" ? "*" : this.mapColumnNamesToSql(this.getTableObject(table), ret).map((col) => this.escapeIdentifier(col)).join(", ");
+					sql += ` RETURNING ${returning}`;
+				}
+				const stmt = db.prepare(sql);
+				if (returningEmpty) {
+					stmt.run(...values);
+					return;
+				}
+				const rows = stmt.all(...values);
+				return this.mapRowFromRawSql(this.getTableObject(table), rows[0]);
+			},
+			insertMany: async (table, data, options) => {
+				if (data.length === 0) return [];
+				const tableObj = this.getTableObject(table);
+				const mappedRecords = data.map((r) => this.mapKeysToSqlColumns(tableObj, r));
+				const columns = Object.keys(mappedRecords[0]);
+				const allValues = [];
+				const valuesClauses = [];
+				for (const record of mappedRecords) {
+					const placeholders = [];
+					for (const col of columns) {
+						allValues.push(sanitizeSqliteValue(record[col]));
+						placeholders.push("?");
+					}
+					valuesClauses.push(`(${placeholders.join(", ")})`);
+				}
+				let sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columns.map((c) => this.escapeIdentifier(c)).join(", ")}) VALUES ${valuesClauses.join(", ")}`;
+				const ret = options?.returning;
+				const returningEmpty = Array.isArray(ret) && ret.length === 0;
+				if (!returningEmpty) {
+					const returning = !ret || ret === "*" ? "*" : this.mapColumnNamesToSql(this.getTableObject(table), ret).map((col) => this.escapeIdentifier(col)).join(", ");
+					sql += ` RETURNING ${returning}`;
+				}
+				const stmt = db.prepare(sql);
+				if (returningEmpty) {
+					stmt.run(...allValues);
+					return [];
+				}
+				return stmt.all(...allValues).map((r) => this.mapRowFromRawSql(tableObj, r));
+			},
+			update: this.transactionUpdate(txDb, (statement, returnsRows) => returnsRows ? txDb().all(statement) : (txDb().run(statement), void 0), sanitizeSqliteValue),
+			...this.createTransactionForwarders(txDb),
+			savepoint: async (name) => {
+				db.exec(`SAVEPOINT ${this.escapeIdentifier(name)}`);
+			},
+			rollbackToSavepoint: async (name) => {
+				db.exec(`ROLLBACK TO SAVEPOINT ${this.escapeIdentifier(name)}`);
+			},
+			releaseSavepoint: async (name) => {
+				db.exec(`RELEASE SAVEPOINT ${this.escapeIdentifier(name)}`);
+			}
+		};
+	}
+	/**
+	* Classifies a SQLite error into a DatabaseError.
+	*
+	* @param error - Original error from better-sqlite3
+	* @param sql - SQL statement that caused the error (optional)
+	* @returns DatabaseError with proper classification
+	*/
+	classifyError(error, sql) {
+		if (isDatabaseError(error)) return error;
+		const sqliteError = this.driverErrorIn(error, (candidate) => typeof candidate.code === "string" && candidate.code !== "");
+		let kind = "unknown";
+		if (sqliteError.code) kind = SQLITE_ERROR_CODES[sqliteError.code] || "unknown";
+		else if (sqliteError.message) {
+			const msg = sqliteError.message.toUpperCase();
+			if (msg.includes("UNIQUE CONSTRAINT")) kind = "unique_violation";
+			else if (msg.includes("FOREIGN KEY CONSTRAINT")) kind = "foreign_key_violation";
+			else if (msg.includes("NOT NULL CONSTRAINT")) kind = "not_null_violation";
+			else if (msg.includes("CHECK CONSTRAINT")) kind = "check_violation";
+			else if (msg.includes("BUSY") || msg.includes("LOCKED")) kind = "timeout";
+			else if (msg.includes("SQLITE_CANTOPEN") || msg.includes("UNABLE TO OPEN")) kind = "connection";
+		}
+		let message = sqliteError.message ?? String(error);
+		if (sql && kind === "query") message = `Query failed: ${message}`;
+		return createDatabaseError({
+			kind,
+			message,
+			code: sqliteError.code,
+			cause: error instanceof Error ? error : void 0
+		});
+	}
 };
+/**
+* Create a SQLite database adapter.
+*
+* @param config - SQLite adapter configuration
+* @returns A new SqliteAdapter instance
+*
+* @example
+* ```typescript
+* // Simple usage with file path
+* const adapter = createSqliteAdapter({
+*   url: 'file:./data.db',
+* });
+*
+* // In-memory database
+* const memAdapter = createSqliteAdapter({
+*   memory: true,
+* });
+*
+* // Full configuration
+* const adapter = createSqliteAdapter({
+*   url: 'file:./data.db',
+*   wal: true,
+*   foreignKeys: true,
+*   busyTimeout: 5000,
+*   logger: {
+*     query: (sql, params, duration) => console.log(`Query: ${sql}`),
+*   },
+* });
+*
+* await adapter.connect();
+* ```
+*/
 function createSqliteAdapter(config) {
-  return new SqliteAdapter(config);
+	return new SqliteAdapter(config);
 }
+/**
+* Type guard to check if a value is a SqliteAdapter.
+*
+* @param value - Value to check
+* @returns True if value is a SqliteAdapter instance
+*
+* @example
+* ```typescript
+* if (isSqliteAdapter(adapter)) {
+*   // TypeScript knows adapter is SqliteAdapter
+*   console.log('Using SQLite');
+* }
+* ```
+*/
 function isSqliteAdapter(value) {
-  return value instanceof SqliteAdapter;
+	return value instanceof SqliteAdapter;
 }
+/**
+* Open the scope of a savepoint inside `parent`, or of an outermost
+* transaction when there is none, and record it among the connection's open
+* scopes.
+*/
 function openScope(parent) {
-  const scope = {
-    active: true,
-    depth: parent ? parent.depth + 1 : 0,
-    parent,
-    rolledBack: false,
-    writesAfterClosing: 0,
-    finished: false,
-    held: [],
-    queue: Promise.resolve(),
-    open: parent ? parent.open : []
-  };
-  scope.open.push(scope);
-  return scope;
+	const scope = {
+		active: true,
+		depth: parent ? parent.depth + 1 : 0,
+		parent,
+		rolledBack: false,
+		writesAfterClosing: 0,
+		finished: false,
+		held: [],
+		queue: Promise.resolve(),
+		open: parent ? parent.open : []
+	};
+	scope.open.push(scope);
+	return scope;
 }
+/** The outermost transaction `scope` runs inside; itself for that one. */
 function outermost(scope) {
-  let at = scope;
-  while (at.parent) at = at.parent;
-  return at;
+	let at = scope;
+	while (at.parent) at = at.parent;
+	return at;
 }
+/**
+* Whether an effect registered from `scope` describes a write that was
+* undone: `scope`, or a scope it runs inside, rolled back, and no
+* transaction had run from its context since it closed when the effect was
+* registered (`writesBefore`). An effect registered before such a write
+* still describes the undone one.
+*/
 function undone(scope, writesBefore) {
-  if (writesBefore > 0) return false;
-  for (let at = scope; at; at = at.parent) {
-    if (at.rolledBack) return true;
-  }
-  return false;
+	if (writesBefore > 0) return false;
+	for (let at = scope; at; at = at.parent) if (at.rolledBack) return true;
+	return false;
+}
+/**
+* Settles once `turn` does, or rejects with the pool-wait timeout error once
+* `boundMs` passes first. A bound of 0 waits without limit, as pg-pool reads a
+* `connectionTimeoutMillis` of 0.
+*/
+function waitForTurn(turn, boundMs) {
+	if (boundMs <= 0) return turn.then(() => void 0);
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(poolWaitTimeoutError(boundMs)), boundMs);
+		timer.unref();
+		turn.then(() => {
+			clearTimeout(timer);
+			resolve();
+		});
+	});
 }
+/** Chain `run` onto a scope's queue, keeping the queue itself unrejected. */
 function enqueueIn(scope, run) {
-  const next = scope.queue.then(run, run);
-  scope.queue = next.catch(() => void 0);
-  return next;
+	const next = scope.queue.then(run, run);
+	scope.queue = next.catch(() => void 0);
+	return next;
 }
+/**
+* Close a scope to new nested calls and wait for those already queued. A call
+* arriving after this joins the innermost scope still open on the connection,
+* or, when none is, goes to the instance queue behind the transaction.
+*/
 async function settleNested(scope) {
-  scope.active = false;
-  const index = scope.open.indexOf(scope);
-  if (index !== -1) scope.open.splice(index, 1);
-  await scope.queue;
+	scope.active = false;
+	const index = scope.open.indexOf(scope);
+	if (index !== -1) scope.open.splice(index, 1);
+	await scope.queue;
 }
-
 export { SqliteAdapter, VERSION, createSqliteAdapter, isSqliteAdapter };
-//# sourceMappingURL=index.mjs.map
+
 //# sourceMappingURL=index.mjs.map