Class IndexedDbAdapter

Storage adapter using IndexedDB + sql.js for client-side SQL persistence.

The Key Difference: Automatic Persistence

sql.js adapter alone:

In-memory SQLite database (lost on page refresh)
You must manually call db.export() and save it yourself
No automatic persistence in browsers
Good for: Edge functions, temporary calculations, prototyping

IndexedDB adapter (this):

Same sql.js SQL engine, but automatically saves to IndexedDB
Data survives page refreshes automatically
Auto-save batching reduces overhead
Good for: Production PWAs, offline-first apps, persistent client-side storage

Is This Necessary?

✅ YES if you need:

Data to survive page refreshes (production apps)
Offline-first functionality (PWAs)
Privacy-first apps (data never leaves browser)
Zero manual save logic (just works)

❌ NO if you:

Only need temporary/in-memory data (edge functions)
Are prototyping and don't care about persistence
Want to manually control when data is saved
Don't need data to survive refreshes

Alternative: You could use sql.js directly and manually save to IndexedDB yourself, but you'd lose:

Automatic batched saves (performance optimization)
Reliable persistence (easy to forget manual saves = data loss)
Consistent API across platforms
Production-ready defaults

Bottom line: This adapter is necessary for production web apps that need persistence. For prototypes or edge functions, sql.js alone is fine.

How It Works:

IndexedDB stores the SQLite database file (binary blob) - this is just storage
sql.js (WASM) loads the database into memory and executes SQL - this provides SQL capabilities
After writes, the updated database is automatically saved back to IndexedDB

Why IndexedDB + sql.js?

IndexedDB alone: NoSQL key-value store, no SQL support
sql.js alone: In-memory SQL, but no automatic persistence (you must manually save)
Combined: Full SQL + automatic browser-native persistence = production-ready solution

Capabilities:

✅ Transactions (via sql.js)
✅ Persistence (via IndexedDB - automatic!)
✅ Full SQL support (via sql.js)
✅ Export/import
❌ Concurrent writes (single-threaded)
❌ Server-side (browser only)

Performance:

Fast reads (in-memory SQL)
Moderate writes (IndexedDB persistence)
Auto-save batching reduces IDB overhead

Example: Client-side application

const adapter = new IndexedDbAdapter({ dbName: 'my-app-db' });
await adapter.open();
await adapter.run('CREATE TABLE sessions (id TEXT PRIMARY KEY, data TEXT)');

Implements

StorageAdapter

Index

Constructors

constructor

new IndexedDbAdapter(options?): IndexedDbAdapter
Parameters
- options: IndexedDbAdapterOptions = {}
Returns IndexedDbAdapter
- Defined in src/adapters/indexedDbAdapter.ts:162

Properties

`Readonly`kind

kind: "indexeddb" = 'indexeddb'

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

`Readonly`capabilities

capabilities: ReadonlySet<StorageCapability> = ...

Capability flags indicating supported features.

Methods

open

open(_options?): Promise<void>
Opens IndexedDB and initializes sql.js database. Loads existing database from IndexedDB if present.
Parameters
- Optional_options: StorageOpenOptions
Returns Promise<void>
Implementation of StorageAdapter.open
- Defined in src/adapters/indexedDbAdapter.ts:174

run

run(statement, parameters?): Promise<StorageRunResult>
Executes a SQL statement that doesn't return rows (INSERT, UPDATE, DELETE, CREATE, etc.).
Parameters
- statement: string
  SQL statement with ? or :name placeholders
- Optionalparameters: StorageParameters
  Positional array or named object
Returns Promise<StorageRunResult>
Result with changes count and last insert row ID
Implementation of StorageAdapter.run
- Defined in src/adapters/indexedDbAdapter.ts:205

get

get<T>(statement, parameters?): Promise<null | T>
Executes a SQL query and returns the first row.
Type Parameters
- T
Parameters
- statement: string
  SELECT statement
- Optionalparameters: StorageParameters
  Query parameters
Returns Promise<null | T>
First row as object or null if no results
Implementation of StorageAdapter.get
- Defined in src/adapters/indexedDbAdapter.ts:239

all

all<T>(statement, parameters?): Promise<T[]>
Executes a SQL query and returns all matching rows.
Type Parameters
- T
Parameters
- statement: string
  SELECT statement
- Optionalparameters: StorageParameters
  Query parameters
Returns Promise<T[]>
Array of result rows as objects
Implementation of StorageAdapter.all
- Defined in src/adapters/indexedDbAdapter.ts:250

exec

exec(script): Promise<void>
Executes a script containing multiple SQL statements.
Parameters
- script: string
Returns Promise<void>
Implementation of StorageAdapter.exec
- Defined in src/adapters/indexedDbAdapter.ts:283

transaction

transaction<T>(fn): Promise<T>
Executes a callback within a database transaction.
Type Parameters
- T
Parameters
- fn: ((trx: StorageAdapter) => Promise<T>)
  - - (trx): Promise<T>
    - Parameters
      trx: StorageAdapter
      Returns Promise<T>
Returns Promise<T>
Implementation of StorageAdapter.transaction
- Defined in src/adapters/indexedDbAdapter.ts:293

beginTransaction

beginTransaction(): Promise<void>
Begins a transaction. sql.js executes all statements in implicit transactions, so this is a no-op for compatibility.

Returns Promise<void>
- Defined in src/adapters/indexedDbAdapter.ts:312

commit

commit(): Promise<void>
Commits the current transaction.

Returns Promise<void>
- Defined in src/adapters/indexedDbAdapter.ts:320

rollback

rollback(): Promise<void>
Rolls back the current transaction.

Returns Promise<void>
- Defined in src/adapters/indexedDbAdapter.ts:329

close

close(): Promise<void>
Closes the database and persists final state to IndexedDB.

Returns Promise<void>
Implementation of StorageAdapter.close
- Defined in src/adapters/indexedDbAdapter.ts:336

exportDatabase

exportDatabase(): Uint8Array
Exports the database as a Uint8Array (SQLite file format). Can be downloaded or stored externally.

Returns Uint8Array
SQLite database file as binary
- Defined in src/adapters/indexedDbAdapter.ts:362

importDatabase

importDatabase(data): Promise<void>
Imports a database from a Uint8Array (SQLite file). Replaces the current database.
Parameters
- data: Uint8Array
  SQLite database file
Returns Promise<void>
- Defined in src/adapters/indexedDbAdapter.ts:372

Class IndexedDbAdapter

Example: Client-side application

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns IndexedDbAdapter

Properties

Readonlykind

Readonlycapabilities

Methods

open

Parameters

Returns Promise<void>

run

Parameters

Returns Promise<StorageRunResult>

get

Type Parameters

Parameters

Returns Promise<null | T>

all

Type Parameters

Parameters

Returns Promise<T[]>

exec

Parameters

Returns Promise<void>

transaction

Type Parameters

Parameters

Parameters

Returns Promise<T>

Returns Promise<T>

beginTransaction

Returns Promise<void>

commit

Returns Promise<void>

rollback

Returns Promise<void>

close

Returns Promise<void>

exportDatabase

Returns Uint8Array

importDatabase

Parameters

Returns Promise<void>

Settings

On This Page

`Readonly`kind

`Readonly`capabilities