Zum Inhalt springen
Deutsch

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.

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.

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)

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.

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 eingebaute node: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.

Terminal-Fenster
npm install better-sqlite3

Auf 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.

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.

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.

Wenn ein PersistentActor startet:

  1. Den neuesten Snapshot aus dem Snapshot-Store laden (falls vorhanden).
  2. SELECT payload FROM events WHERE persistence_id = ? AND sequence_nr >= ? ausführen, um Events nach dem Snapshot zu streamen.
  3. Jedes Event über onEvent anwenden.

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.

Da das Journal eine einzelne SQLite-Datei ist:

Terminal-Fenster
# Backup (mit WAL — verwende SQLites Online-Backup):
sqlite3 events.db ".backup events-$(date +%F).db"
# Oder die App stoppen + cp:
systemctl stop my-app
cp events.db events.db.bak
systemctl start my-app

Online-Backup ist bevorzugt — keine Downtime, konsistenter Snapshot. Das Standard-SQLite-Tooling gilt.

Drei Signale, dass du dem Single-File-SQLite entwachsen bist:

  1. 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.
  2. Anhaltend 100K+ Events/sec — SQLite kann das mit Tuning handhaben, aber du bist an den Rändern; spaltenorientierte / verteilte Engines sind dafür entworfen.
  3. 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.