Class BetterSqliteAdapter

constructor

• new BetterSqliteAdapter(defaultFilePath): BetterSqliteAdapter

• Creates a new better-sqlite3 adapter instance.

  Parameters

  • defaultFilePath: string

    Absolute path to the SQLite database file. Will be created if it doesn't exist.

  Returns BetterSqliteAdapter

Readonlykind

Readonlycapabilities

open

• open(options?): Promise<void>

• Open (or no-op if already open) the underlying native database.

  Throws a descriptive error if called in a browser environment.

  Parameters

  • Optionaloptions: StorageOpenOptions

  Returns Promise<void>

run

• run(statement, parameters?): Promise<StorageRunResult>

• Executes a mutation statement (INSERT, UPDATE, DELETE).

  Parameters

  • statement: string

    SQL statement to execute
  • Optionalparameters: StorageParameters

    Optional parameters for the statement

  Returns Promise<StorageRunResult>

  Metadata about affected rows

  Throws

  If statement execution fails

  Example

  const result = await adapter.run('INSERT INTO users (name) VALUES (?)', ['John']);
  console.log(`Inserted with ID: ${result.lastInsertRowid}`);
  Copy

get

• get<T>(statement, parameters?): Promise<null | T>

• Retrieves a single row (or null if none found).

  Type Parameters

  • T = unknown

  Parameters

  • statement: string

    SQL SELECT statement
  • Optionalparameters: StorageParameters

    Optional parameters for the statement

  Returns Promise<null | T>

  First row or null if no results

  Throws

  If query execution fails

  Example

  const user = await adapter.get<User>('SELECT * FROM users WHERE id = ?', [123]);
  Copy

all

• all<T>(statement, parameters?): Promise<T[]>

• Retrieves all rows returned by the statement.

  WARNING: For large result sets, this loads everything into memory. Consider using streaming (if supported) for large queries.

  Type Parameters

  • T

  Parameters

  • statement: string

    SQL SELECT statement
  • Optionalparameters: StorageParameters

    Optional parameters for the statement

  Returns Promise<T[]>

  Array of all matching rows (empty array if none)

  Throws

  If query execution fails

  Example

  const users = await adapter.all<User>('SELECT * FROM users WHERE age > ?', [18]);
  Copy

exec

• exec(script): Promise<void>

• Executes a script containing multiple SQL statements.

  Statements are typically delimited by semicolons. This is useful for running migrations or initialization scripts. No results are returned.

  Parameters

  • script: string

    SQL script with multiple statements

  Returns Promise<void>

  Throws

  If any statement in the script fails

  Example

  await adapter.exec(`
    CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
    CREATE INDEX idx_users_name ON users(name);
  `);
  Copy

transaction

• transaction<T>(fn): Promise<T>

• Executes a callback within a database transaction.

  The transaction is automatically committed on success or rolled back on error. Nested transactions may not be supported by all adapters.

  Type Parameters

  • T

  Parameters

  • fn: ((trx: StorageAdapter) => Promise<T>)

    Async callback to execute within the transaction

    • • (trx): Promise<T>

      • Parameters

        • trx: StorageAdapter

        Returns Promise<T>

  Returns Promise<T>

  Result of the callback function

  Throws

  Transaction is rolled back and error is re-thrown

  Example

  const result = await adapter.transaction(async (trx) => {
    await trx.run('INSERT INTO accounts (balance) VALUES (?)', [100]);
    await trx.run('INSERT INTO logs (action) VALUES (?)', ['account_created']);
    return { success: true };
  });
  Copy

close

• close(): Promise<void>

• Closes the underlying connection and releases resources.

  After calling close(), the adapter should not be used again. Always close adapters when done to prevent resource leaks.

  Returns Promise<void>

  Example

  try {
    await adapter.open();
    // ... use adapter ...
  } finally {
    await adapter.close();
  }
  Copy

batch

• batch(operations): Promise<BatchResult>

• Execute multiple operations efficiently in a single transaction.

  Much faster than executing operations individually, especially for bulk inserts. Automatically wraps in a transaction.

  Parameters

  • operations: BatchOperation[]

    Array of SQL operations to execute

  Returns Promise<BatchResult>

  Results of the batch operation