Interface StorageAdapter

Core SQL storage adapter interface.

Every adapter implementation must fulfill this contract to ensure compatibility across different SQL backends. Check the capabilities property to determine which optional features are supported.

Error Handling

All methods should throw meaningful errors when operations fail. Adapters should not silently fail or return undefined on errors.

Thread Safety

Adapters should document their thread-safety guarantees. SQLite adapters typically don't support concurrent writes, while PostgreSQL does.

interface StorageAdapter {
    kind: string;
    capabilities: ReadonlySet<StorageCapability>;
    open(options?: StorageOpenOptions): Promise<void>;
    run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
    get<T>(statement: string, parameters?: StorageParameters): Promise<null | T>;
    all<T>(statement: string, parameters?: StorageParameters): Promise<T[]>;
    exec(script: string): Promise<void>;
    transaction<T>(fn: ((trx: StorageAdapter) => Promise<T>)): Promise<T>;
    close(): Promise<void>;
    batch?(operations: BatchOperation[]): Promise<BatchResult>;
    prepare?<T>(statement: string): PreparedStatement<T>;
}

Implemented by

Properties

kind capabilities

Methods

open run get all exec transaction close batch? prepare?

Properties

Readonlykind

kind: string

Identifier for logging/diagnostics (e.g., 'better-sqlite3', 'postgres').

Readonlycapabilities

capabilities: ReadonlySet<StorageCapability>

Capability flags indicating supported features.

Methods

open

  • open(options?): Promise<void>

  • Opens the underlying connection or initializes the backing store.

    Parameters

    Returns Promise<void>

    Throws

    If connection cannot be established

    Example

    await adapter.open({ filePath: '/path/to/db.sqlite3' });

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}`);

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]);

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 = unknown

    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]);

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);
    `);

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

    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 };
    });

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();
    }

Optionalbatch

  • batch(operations): Promise<BatchResult>

  • Executes multiple operations in a batch (if supported).

    This is more efficient than executing operations individually, especially for bulk inserts. Check if 'batch' capability is present.

    Parameters

    Returns Promise<BatchResult>

    Batch execution results

    Throws

    If adapter doesn't support batch operations

    Example

    if (adapter.capabilities.has('batch')) {
      const result = await adapter.batch([
        { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Alice'] },
        { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Bob'] }
      ]);
    }

Optionalprepare

  • prepare<T>(statement): PreparedStatement<T>

  • Returns a prepared statement for repeated execution (if supported).

    Prepared statements improve performance for frequently executed queries and provide better protection against SQL injection. Check if 'prepared' capability is present.

    Type Parameters

    • T = unknown

    Parameters

    • statement: string

      SQL statement to prepare

    Returns PreparedStatement<T>

    Prepared statement handle

    Throws

    If adapter doesn't support prepared statements

Settings

Member Visibility

On This Page

Error HandlingThread Safety
Properties
Methods