SQLite snapshot store

SqliteSnapshotStore persists snapshots to a SQLite file — durable, zero-dependency on Bun, peer-dep on Node. Pair with SqliteJournal for the standard single-node production setup.

import { SqliteJournal, SqliteSnapshotStore, PersistenceExtensionId, ActorSystem } from 'actor-ts';

const system = ActorSystem.create('my-app');
system.extension(PersistenceExtensionId).configure({
  journal: new SqliteJournal({
    path: '/var/lib/my-app/events.db',
    wal:  true,
  }),
  snapshotStore: new SqliteSnapshotStore({
    path: '/var/lib/my-app/snapshots.db',
    wal:  true,
  }),
});

Configuration

interface SqliteSnapshotStoreOptions {
  path?:           string;     // file path, or ':memory:'
  snapshotsTable?: string;     // default 'snapshots'
  wal?:            boolean;    // enable WAL mode
  driver?:         SqliteDriver;
}

Same fields as the journal — see SQLite journal for the full discussion of each.

Schema

CREATE TABLE snapshots (
  pid     TEXT NOT NULL,
  seq     INTEGER NOT NULL,
  state   BLOB NOT NULL,
  ts      INTEGER NOT NULL,
  PRIMARY KEY (pid, seq)
);

Same pattern as the journal: keyed by (pid, seq). The framework reads the highest seq for a given pid on loadLatest.

Pairing with the journal

// Production:
{
  journal:       new SqliteJournal({ path: '/var/lib/events.db' }),
  snapshotStore: new SqliteSnapshotStore({ path: '/var/lib/snapshots.db' }),
}

The journal and snapshot store are independent files. You can also put them in the same file with different table names — but two files keep operations simpler (back up independently, vacuum independently).

For multi-node deployments where the journal is Cassandra, you can still use SQLite for snapshots if each entity always recovers on the same node. But for sharded entities (which move between nodes), the snapshot store also needs to be shared — see Object storage snapshot store.

Performance

• Snapshot write — single INSERT, ~100 μs. Dominated by serialization, not SQLite I/O.
• Snapshot read — single SELECT, sub-millisecond.

For very-large snapshots (multi-MB state), serialization is the bottleneck. Consider compression (Object storage compression) or a different snapshot strategy.

Where to next

• Snapshots — the policy + mechanics.
• SQLite journal — the journal you pair this with.
• In-memory snapshot store — for tests.
• Cached snapshot store — read-through cache.

The SqliteSnapshotStore API reference covers the full options.