Actors/Packages/SQLite
@sigx/actors-sqlite · Preview

SQLite#

The step up from fileStorage for a single-node host: a real database in one file, on Node's built-in node:sqlite, with nothing to install and nothing to operate.

v0.11.0 MIT

Installation#

Terminal 
pnpm add @sigx/actors-sqlite

Node-only, Node ≥ 22.13. There are no runtime dependencies beyond the @sigx/actors peer.

What it provides#

One export, sqliteStorage() — an etag-CAS ActorStorage with one row per actor in a table keyed by (type, key).

TypeScript 
import { createHost } from '@sigx/actors/host';
import { sqliteStorage } from '@sigx/actors-sqlite';

const storage = sqliteStorage({ path: './actors.db' });
const host = createHost({ actors, storage });

// …on shutdown
await host.stop();
storage.close();

The table is created on open (IF NOT EXISTS), so there is no DDL step. A load is one B-tree probe and a save is one statement. sqliteStorage implements both optional fast paths of the seam — saveText, so a durable save walks the state once, and appendText, so ctx.append writes one entry rather than the whole state.

When to use it#

Use
fileStorage({ dir })dev — one cat-able JSON file per actor
sqliteStorage({ path })a single-node host that wants durable state in one file
@sigx/actors-redis, @sigx/actors-pga cluster

Not a cluster store. Two hosts pointing at one file serialize on SQLite's write lock. The 5 s busy_timeout makes the second writer wait instead of failing, but the cluster-safe options are @sigx/actors-redis and @sigx/actors-pg.

The experimental warning#

node:sqlite is unflagged from Node 22.13 but still marked experimental. The process prints one line to stderr on first import:

ExperimentalWarning: SQLite is an experimental feature

It is harmless. node --disable-warning=ExperimentalWarning silences it.

Next steps#