SQLite-Journal
SqliteJournal speichert Events in einer SQLite-Datenbank — eine
einzelne Datei auf der Disk, durable, kein separater Server. Es
ist der richtige Default für Single-Node-Produktion: auf Bun
ist der Treiber eingebaut (bun:sqlite, keine Installation), auf
Node ist es eine einzelne Peer-Dep (better-sqlite3). Überlebt
Neustarts, schnell genug für die meisten Workloads.
import { ActorSystem, ActorSystemOptions,} from 'actor-ts';import { SqliteJournal, SqliteJournalOptions, SqliteSnapshotStore, SqliteSnapshotStoreOptions,} from 'actor-ts/persistence';
const sqliteJournalOptions = SqliteJournalOptions.create() .withPath('/var/lib/my-app/events.db') .withWal(true);const sqliteSnapshotStoreOptions = SqliteSnapshotStoreOptions.create().withPath('/var/lib/my-app/snapshots.db');const systemOptions = ActorSystemOptions.create().withPersistence({ journal: new SqliteJournal(sqliteJournalOptions), snapshotStore: new SqliteSnapshotStore(sqliteSnapshotStoreOptions),});const system = ActorSystem.create('my-app', systemOptions);Eine einzelne Datei pro System; das Actor-System schreibt durch SQLite in den OS-Page-Cache, der beim Commit auf Disk flusht. Stores, die in den Optionen des Systems gesetzt sind, öffnen als Teil seines Starts, also lässt eine Datei, die der Knoten nicht öffnen kann, den Start scheitern statt erst die erste persistierte Nachricht — siehe Stores beim Start öffnen.
Als Plugin registrieren
Abschnitt betitelt „Als Plugin registrieren“Die Optionen oben verdrahten die Stores direkt — der kürzeste Weg, und völlig in
Ordnung für eine App, die ohnehin nie etwas anderes als SQLite nutzt. Der
andere Weg ist, SQLite als Plugin zu registrieren und die Auswahl der
Konfiguration zu überlassen — genau das bedeutet
actor-ts.persistence.journal.plugin seit jeher, und registerSqlitePlugins
macht es nun auch für SQLite wahr:
import { ActorSystem, ActorSystemOptions } from 'actor-ts';import { registerSqlitePlugins } from 'actor-ts/persistence';
const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [(persistence) => registerSqlitePlugins(persistence)],});const system = ActorSystem.create('my-app', systemOptions);actor-ts.persistence { journal { plugin = "actor-ts.persistence.journal.sqlite" } snapshot-store { plugin = "actor-ts.persistence.snapshot-store.sqlite" } durable-state { plugin = "actor-ts.persistence.durable-state.sqlite" }
journal.sqlite { path = "/var/lib/my-app/app.db", wal = on } snapshot-store.sqlite { path = "/var/lib/my-app/app.db", keep-n = 5 } durable-state.sqlite { path = "/var/lib/my-app/app.db" }}Das ist die ganze Verdrahtung: die Plugin-Id ist der Config-Abschnitt, der
Block mit dem Namen der Id ist also der Block, den dieses Plugin liest. Nichts
an der Datenbank steckt mehr im Code — Pfad, Tabellennamen, wal, keep-n und
der Busy-Timeout wandern mit der Umgebung, und genau dafür gibt es eine
Config-Datei.
Jeder Store, den ein Selektor benennt, muss seine Datenbank benennen. Das
ausgelieferte path = "" heißt nicht gesetzt, und dahinter steht kein
In-Memory-Fallback: ein ausgewählter Store, dessen Block und Code-Options den
Pfad offen lassen, wird abgelehnt, wenn registerSqlitePlugins läuft, sodass
ActorSystem.create mit einem Fehler wirft, der den zu setzenden Key nennt.
path = ":memory:" ist der Weg zu einer In-Memory-Datenbank. Ein registrierter,
aber nicht ausgewählter Store wird nie gebaut und braucht daher nichts.
An registerSqlitePlugins übergebene Options gewinnen weiterhin, Feld für Feld,
und ein nicht gesetztes Feld fällt auf den Block durch, statt ihn zu leeren:
// path and tables from HOCON; the serializer only expressible in code.const sqlitePluginsOptions = RegisterSqlitePluginsOptions.create().withSerializer(myCborSerializer);const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [(persistence) => registerSqlitePlugins(persistence, sqlitePluginsOptions)],});Ein hier angegebener path ist ein gemeinsamer Default — ein Store-Block
mit eigenem Pfad behält seinen —, eine vorab geöffnete database dagegen ein
Override für den Durable-State-Store, den einzigen SQLite-Store, der ein
Handle annimmt. Journal und Snapshot-Store öffnen ihre eigene Datei; ein hier
übergebenes Handle erreicht sie also nicht, und ein ausgewählter braucht
weiterhin einen Pfad. Für driver, database und serializer gibt es kein
Config-Blatt: das sind lebende Objekte, die eine Config-Datei nicht ausdrücken
kann.
Die vollständige Key-Tabelle steht in der Konfigurationsreferenz.
Konfiguration
Abschnitt betitelt „Konfiguration“type SqliteJournalOptions = { path?: string; // Pflicht: ein Dateipfad, oder ":memory:" für eine In-Memory-DB eventsTable?: string; // Default "events" wal?: boolean; // WAL-Modus aktivieren (empfohlen) busyTimeoutMs?: number; // Lock-Wartebudget, Default 1000; 0 = sofort scheitern driver?: SqliteDriver; // expliziter Treiber-Override};const sqliteJournalOptions = SqliteJournalOptions.create().withPath('/var/lib/my-app/events.db');new SqliteJournal(sqliteJournalOptions)Die Datenbank-Datei, und sie ist Pflicht. Absolute Pfade sind
am besten — relative Pfade werden ab process.cwd() aufgelöst, was
dich überraschen kann. Die Datei wird erstellt, wenn sie nicht
existiert; bestehende Dateien werden wiederverwendet (Events appenden
in place).
Einen Default, auf den zurückgefallen würde, gibt es nicht. Ein
Journal ohne Pfad wirft bei der Konstruktion einen OptionsError,
ebenso ein leerer Pfad oder eine entfernte URL — libsql://,
https://, wss:// gehören zu
libSQL / Turso. Eine
In-Memory-Datenbank ist eine ausdrückliche Wahl, nicht das, was ein
fehlender Pfad bedeutet: für Tests verwende ':memory:' — eine
SQLite-gestützte In-Memory-DB, die sich genau wie die Datei-Version
verhält, aber mit dem Prozess verschwindet:
const sqliteJournalOptions = SqliteJournalOptions.create().withPath(':memory:');new SqliteJournal(sqliteJournalOptions)eventsTable
Abschnitt betitelt „eventsTable“Default 'events'. Überschreibe das, wenn du willst, dass mehrere
Systeme sich eine DB-Datei teilen (z. B. Dev-Rig):
const sqliteJournalOptions = SqliteJournalOptions.create() .withPath('shared.db') .withEventsTable('orders_events');new SqliteJournal(sqliteJournalOptions)Der Name ist ein Stamm, nicht nur eine Tabelle: Der Tag-Index und
die Compaction-High-Water-Mark leiten sich davon ab, orders_events
liefert dir also auch orders_events_tags und orders_events_meta.
Das Framework erstellt sie alle automatisch, wenn der Store öffnet — beim
Start, oder bei der ersten Verwendung, wenn das Öffnen beim Start
abgeschaltet ist; siehe Schema.
const sqliteJournalOptions = SqliteJournalOptions.create() .withPath('...') .withWal(true);new SqliteJournal(sqliteJournalOptions)Aktiviert den Write-Ahead-Logging-Modus. Empfohlen für Produktion. WAL gibt dir:
- Bessere Concurrency — Reader blockieren den Writer nicht.
- Schnellere Commits — WAL-Writes sind sequenziell, dann wird der Checkpoint gebatched.
- Sicherere Crashes — Recovery ist einfacher als im Rollback-Journal-Modus.
Der Default ist aus, um den Defaults von SQLite zu entsprechen; aktiviere es explizit, wenn du in Produktion gehst.
busyTimeoutMs
Abschnitt betitelt „busyTimeoutMs“const sqliteJournalOptions = SqliteJournalOptions.create() .withPath('...') .withBusyTimeoutMs(1000);new SqliteJournal(sqliteJournalOptions)Wie lange ein Write auf das Datenbank-Lock wartet, bevor er mit
SQLITE_BUSY aufgibt. Default 1000 ms. 0 schaltet das Warten
ab — ein Write unter Contention scheitert beim ersten Versuch.
Diesen Wert setzt das Framework bewusst selbst, weil die Treiber sich
nicht einig sind. Ihre eingebauten Defaults sind 0 ms bei bun:sqlite
und node:sqlite, aber 5000 ms bei better-sqlite3 — ohne expliziten
Wert würde dasselbe Journal auf Bun und Deno sofort scheitern und auf
Node fünf Sekunden blockieren. Das Framework prägt jeder Verbindung,
die es öffnet, seinen eigenen Wert auf; genau das lässt die drei
Runtimes gleich verhalten.
Wähle einen eigenen Wert mit einer Sache im Kopf: die SQLite-Treiber
sind synchron, das Warten ist also keine Leerlaufzeit — es
blockiert die Event-Loop, und solange es dauert, läuft nichts anderes
im Prozess, Cluster-Heartbeats eingeschlossen. Deshalb liegt der
Default bei 1000 ms statt bei den 5000 ms von better-sqlite3: der
Cluster-Failure-Detector erklärt einen Node nach 2000 ms für
unerreichbar, ein Fünf-Sekunden-Stall wäre also lang genug, damit die
eigenen Peers einen Node aufgeben. Erhöhe ihn nur, wenn du weißt,
dass deine Contention kurzlebig ist und dein Node nicht im Cluster
steht.
Ein negativer Wert wird abgelehnt — SQLite liest ihn als „ewig weiterversuchen“, was auf einem synchronen Treiber ein unbegrenztes Einfrieren bedeutet.
Das Framework erkennt den richtigen Treiber basierend auf der
Runtime automatisch, sodass du driver normalerweise ungesetzt
lässt:
- Bun →
bun:sqlite(eingebaut). - Node →
better-sqlite3, wenn installiert, sonst das eingebautenode:sqlite. - Deno →
node:sqlite(eingebaut, Deno >= 2.2).
Die Auto-Detection deckt jede unterstützte Runtime ab, und jede von
ihnen hat einen Treiber, der keine Installation braucht. Die
konkreten Treiber-Klassen sind nicht Teil der öffentlichen API — es
gibt keinen Import-Pfad, um selbst einen zu konstruieren — daher ist
der driver-Slot eine interne Naht, die die Tests des Frameworks
verwenden, nichts, was du in Anwendungscode verdrahtest.
Jeder Store führt CREATE TABLE IF NOT EXISTS aus, wenn er öffnet — beim
Start, oder bei der ersten Verwendung, wenn das Öffnen beim Start
abgeschaltet ist —, eine leere Datei ist also ein gültiger Startpunkt. Fünf Tabellen,
verteilt auf die drei Stores:
CREATE TABLE events ( persistence_id TEXT NOT NULL, sequence_nr INTEGER NOT NULL, payload TEXT NOT NULL, -- JSON tags TEXT, -- legacy CSV (auch nach events_tags gespiegelt) timestamp INTEGER NOT NULL, PRIMARY KEY (persistence_id, sequence_nr));CREATE INDEX idx_events_pid ON events(persistence_id);
CREATE TABLE events_tags ( -- indizierte Tag-Lookups für Projektionen persistence_id TEXT NOT NULL, sequence_nr INTEGER NOT NULL, tag TEXT NOT NULL, timestamp INTEGER NOT NULL, PRIMARY KEY (tag, timestamp, persistence_id, sequence_nr));CREATE INDEX idx_events_tags_pid_seq ON events_tags(persistence_id, sequence_nr);
CREATE TABLE events_meta ( -- Compaction-High-Water-Mark persistence_id TEXT PRIMARY KEY, deleted_to INTEGER NOT NULL);
CREATE TABLE snapshots ( persistence_id TEXT NOT NULL, sequence_nr INTEGER NOT NULL, payload TEXT NOT NULL, timestamp INTEGER NOT NULL, PRIMARY KEY (persistence_id, sequence_nr));
CREATE TABLE durable_state ( persistence_id TEXT PRIMARY KEY, revision INTEGER NOT NULL, payload TEXT NOT NULL, timestamp INTEGER NOT NULL);Die Namen oben sind die Defaults; eventsTable, snapshotsTable und die
table-Option des Durable-State-Stores benennen sie um, und events_tags
/ events_meta folgen dem Stamm des Journals.
Zwei Details, die du kennen solltest. Das Dual-Table-Design für Tags
ist der Grund, warum Projektionen skalieren: events.tags behält die
Legacy-CSV-Spalte aus Rückwärtskompatibilität, aber Tag-Queries lesen
events_tags und treffen damit einen Index, statt jede Zeile zu scannen.
Beide werden in derselben Transaktion geschrieben, können also nicht
auseinanderlaufen.
Und der Primary Key von events ist hier die Absicherung, nicht der
Concurrency-Mechanismus. Lokal liest das Journal die Head-Sequence
innerhalb einer BEGIN IMMEDIATE-Transaktion erneut und wirft einen
JournalConcurrencyError, bevor überhaupt ein Insert versucht wird. Die
HTTP-basierten Backends haben keine solche Transaktion, lassen den Write
also auf (persistence_id, sequence_nr) laufen und übersetzen
stattdessen das UNIQUE constraint failed — dieselben Tabellen,
schwächere Garantie.
Das ist das Schema des SQLite-Dialekts, wortgleich geteilt mit libSQL / Turso und Cloudflare D1 — auf allen dreien läuft dieselbe DDL, und genau das lässt eine Datenbank ohne Migration zwischen einer lokalen Datei und einem der beiden wechseln.
Peer-Dependency auf Node — optional
Abschnitt betitelt „Peer-Dependency auf Node — optional“npm install better-sqlite3Auf Node ist better-sqlite3 eine optionale Peer-Dependency:
installiert bevorzugt das Framework es, ohne es übernimmt das
eingebaute node:sqlite. Es lohnt sich, wenn du den zusätzlichen
Durchsatz willst oder dein Deployment es schon einsetzt; andernfalls
ist der Zero-Dependency-Pfad ein nativer Build weniger im Image.
Bun und Deno brauchen nichts: bun:sqlite und node:sqlite sind
eingebaut.
Für eine entfernte SQLite-Datenbank siehe libSQL / Turso — gleiches Schema, über HTTP erreichbar.
Durable State
Abschnitt betitelt „Durable State“Neben Journal und Snapshot-Store gibt es für SQLite einen
DurableStateStore — das Modell „nur den aktuellen Wert halten”, ohne
Event-Log und ohne Replay:
import { SqliteDurableStateStore, SqliteDurableStateStoreOptions } from 'actor-ts/persistence';
const stateOptions = SqliteDurableStateStoreOptions.create() .withPath('./state.db');const store = new SqliteDurableStateStore(stateOptions);Er ist der einzige SQLite-Store, der statt eines Pfads ein Datenbank-Handle annimmt — Journal und Snapshot-Store öffnen ihre eigene Datei, gib ihnen also einen Pfad. Um ihm eines zu geben, das du selbst geöffnet hast und das auch dein eigener Code nutzt, übergib es; der Store überlässt das Schließen dann dir:
import { getSqliteDriver } from 'actor-ts/persistence';
const driver = await getSqliteDriver();const database = driver.open('./app.db');
const sharedOptions = SqliteDurableStateStoreOptions.create() .withDatabase(database);Ein Handle, das du selbst geöffnet hast, lässt der Store unangetastet
— busyTimeoutMs eingeschlossen: der Store wendet es nur auf
Verbindungen an, die er selbst öffnet, denn das Pragma gilt pro
Verbindung, und ein geteiltes Handle nachzujustieren würde in alles
hineingreifen, was es sonst noch nutzt. Setze es auf einem eigenen
Handle selbst:
database.exec('PRAGMA busy_timeout = 1000;');Seine Tabelle ist die durable_state aus Schema — die des
SQLite-Dialekts und damit identisch zu dem, was
libSQL / Turso und
Cloudflare D1 ausführen — eine
Datenbank kann also ohne Migration zwischen einer lokalen Datei und
einem der beiden wandern.
Ein Unterschied in die andere Richtung ist erwähnenswert: weil hier eine
lokale Datei statt HTTP im Spiel ist, sind die Transaktionen ein echtes
BEGIN IMMEDIATE … COMMIT. Die HTTP-basierten SQLite-Backends können
nur einen atomaren Batch anbieten — genau deshalb legt SqlPool die
Isolation als adapterdefiniert fest. Dieses Backend liefert mehr, als
der Vertrag verlangt.
Eine entfernte URL wird bei der Konstruktion abgelehnt, von allen drei
SQLite-Stores und nicht nur von diesem: withPath('libsql://…') wirft
und verweist auf die libSQL-Stores — der lokale Treiber kann sie nicht
öffnen, und stillschweigend eine Datei mit diesem Namen anzulegen wäre
das verwirrende Ergebnis. Ein leerer Pfad wird genauso abgelehnt, ein
fehlender, sofern kein Datenbank-Handle an seine Stelle tritt.
Die Auto-Detection importiert better-sqlite3 erst, wenn das Framework
tatsächlich eine SQLite-Datenbank öffnet — beim Start für einen Store, den
das System dort öffnet, oder bei der ersten Verwendung, wenn das Öffnen beim
Start abgeschaltet ist. Wenn du
auf Bun bist und nie SQLite verwendest, spielt der fehlende Peer
keine Rolle.
Wie es performt
Abschnitt betitelt „Wie es performt“Grobe Zahlen (NVMe-Disk, Default-Settings):
- Append-Durchsatz — 10 000-50 000 Events/sec für kleine Events. WAL-Modus hilft signifikant.
- Read-Durchsatz — 100 000+ Events/sec für Recovery (sequenzieller Scan).
- Gleichzeitige Reader — viele parallele Reader blockieren im WAL-Modus keine Writer.
Für eine Single-Node-App mit ein paar Tausend Actors, die Events pro Sekunde emittieren, ist SQLite reichlich schnell. Für Zehntausende von Events pro Sekunde dauerhaft, überlege:
- SQLite-Pragmas tunen (
synchronous = NORMAL,journal_mode = WAL, größerer Cache). - Über mehrere Journals sharden.
- Zu Cassandra für Multi-Node-Verteilung wechseln.
Recovery-Flow
Abschnitt betitelt „Recovery-Flow“Wenn ein PersistentActor startet:
- Den neuesten Snapshot aus dem Snapshot-Store laden (falls vorhanden).
SELECT payload FROM events WHERE persistence_id = ? AND sequence_nr >= ?ausführen, um Events nach dem Snapshot zu streamen.- Jedes Event über
onEventanwenden.
Für ein 100 000-Event-Journal ohne Snapshot liest die Recovery alle 100 000 Zeilen. Sequenzieller Scan mit einem Prepared Statement — Sub-Sekunde auf moderner Hardware, aber richte Snapshots ein für jeden Actor, der Events akkumuliert.
Siehe Snapshots.
Backup + Restore
Abschnitt betitelt „Backup + Restore“Da das Journal eine einzelne SQLite-Datei ist:
# Backup (mit WAL — verwende SQLites Online-Backup):sqlite3 events.db ".backup events-$(date +%F).db"
# Oder die App stoppen + cp:systemctl stop my-appcp events.db events.db.baksystemctl start my-appOnline-Backup ist bevorzugt — keine Downtime, konsistenter Snapshot. Das Standard-SQLite-Tooling gilt.
Stolperfallen
Abschnitt betitelt „Stolperfallen“Wenn SQLite nicht reicht
Abschnitt betitelt „Wenn SQLite nicht reicht“Drei Signale, dass du dem Single-File-SQLite entwachsen bist:
- Multi-Node — du brauchst Actors auf N Nodes, die sich denselben Event-Stream teilen. SQLite pro Node skaliert hier nicht bloß schlecht, es korrumpiert lautlos: jeder Knoten replayt seine eigene Datei, eine verschobene Entity recovert also eine andere Historie, ohne Fehler irgendwo (das Cluster warnt — Storage-Lokalität). Wechsle zu einem geteilten Backend: Cassandra, PostgreSQL oder jede Zeile „Über Knoten geteilt” der Backend-Matrix.
- Anhaltend 100K+ Events/sec — SQLite kann das mit Tuning handhaben, aber du bist an den Rändern; spaltenorientierte / verteilte Engines sind dafür entworfen.
- Große Events (> 1 MB pro Stück) — SQLite speichert jedes
Event als JSON-
TEXT-Payload; die Read-Performance degradiert. Überlege Event-Compaction (Pointer zu externem Storage speichern) oder ein Journal, das für große Payloads entworfen ist.
Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- Persistenz im Überblick — das größere Bild.
- In-Memory-Journal — für Tests und Dev.
- Cassandra-Journal — für Multi-Node-Produktion.
- Snapshots — um den Recovery-Scan zu begrenzen.
- Snapshot Stores — SQLite — der zugehörige Snapshot-Store.
- Migrations-Rezepte — Schema-Evolution auf einem lange laufenden Journal.
