MongoDB
Das MongoDB-Backend liefert alle vier Persistence-Komponenten gegen ein einzelnes
MongoDB-Deployment, über den
mongodb-Treiber:
MongoJournal— das Event-Journal fürPersistentActors.MongoSnapshotStore— Snapshots, um die Recovery zu begrenzen.MongoDurableStateStore— Key-Value-Durable-State fürDurableStateActors.MongoQuery— ein indiziertescurrentEventsByTag, das die relationalen Backends nicht haben.
Es ist das erste Document-Store-Backend und braucht kein Replica Set: siehe Keine Transaktionen nötig.
Installation
Abschnitt betitelt „Installation“mongodb ist eine optionale Peer-Dependency. Version 6 und Version 7 werden
beide unterstützt:
bun add mongodb@^7 # oder mongodb@^6Das Framework importiert den Treiber erst, wenn ein MongoDB-Store öffnet — beim Start, oder bei der ersten Verwendung, wenn das Öffnen beim Start abgeschaltet ist —; bis dahin bleibt er aus deinem Bundle heraus.
Einrichtung
Abschnitt betitelt „Einrichtung“Registriere alle drei Stores über den plugins-Slot der Optionen des Systems
und wähle sie in seiner Konfiguration aus. Setz die Verbindung einmal am
Composite, dann erben sie alle drei Komponenten:
import { ActorSystem, ActorSystemOptions,} from 'actor-ts';import { MongoDurableStateStoreOptions, MongoJournalOptions, MongoSnapshotStoreOptions, RegisterMongoPluginsOptions, registerMongoPlugins,} from 'actor-ts/persistence';
const mongoSnapshotStoreOptions = MongoSnapshotStoreOptions.create() .withKeepN(3);const registerOptions = RegisterMongoPluginsOptions.create() .withUrl('mongodb://user:pass@localhost:27017') .withDatabaseName('app') .withJournal(MongoJournalOptions.create() /* .withEventsCollection(...) */) .withSnapshotStore(mongoSnapshotStoreOptions) .withDurableStateStore(MongoDurableStateStoreOptions.create() /* .withCollection(...) */);const systemOptions = ActorSystemOptions.create() // Select the MongoDB plugins for all three stores. .withConfig({ 'actor-ts': { persistence: { journal: { plugin: 'actor-ts.persistence.journal.mongodb' }, 'snapshot-store': { plugin: 'actor-ts.persistence.snapshot-store.mongodb' }, 'durable-state': { plugin: 'actor-ts.persistence.durable-state.mongodb' }, }, }, }) .withPersistence({ plugins: [(persistence) => registerMongoPlugins(persistence, registerOptions)] });const system = ActorSystem.create('my-app', systemOptions);Das Plug-in läuft innerhalb von ActorSystem.create und registriert alle drei
Stores — Journal, Snapshot-Store und seit #872 auch den Durable-State-Store, den
der Schlüssel durable-state.plugin jetzt genauso auswählt wie die beiden
anderen —, also öffnen die, die die Konfiguration auswählt, als Teil des Starts:
Ein Deployment, das der Knoten nicht erreicht, lässt den Start scheitern statt
erst die erste persistierte Nachricht — siehe Stores beim Start
öffnen. Das gilt, wie
auch immer ein Store eingerichtet ist, solange das Öffnen beim Start an ist,
der Default. Jedes Öffnen schickt ein { ping: 1 },
bevor es einen Index anlegt — auch mit abgeschaltetem auto-create-indexes,
über einen übergebenen Client und für den Durable-State-Store, der gar keinen
Index anlegt —, und ein abgelehnter Ping lässt das Öffnen mit einem Fehler
scheitern, der den Store nennt. Der Ping braucht kein Recht, liest nichts und
legt nichts an. Er geht über das command des Datenbank-Handles, das das
Handle des Treibers immer hat; ein Ersatz, der ohne es übergeben wird, wird
nicht angepingt. Das gilt für diese Stores, nicht für jede Achse: Ein
Object-Storage-Snapshot- oder -Durable-State-Store, der daneben ausgewählt ist,
oder ein eigener Store ohne start() hat vorab nichts zu öffnen und scheitert
stattdessen bei seiner ersten Operation. Das
zurückgegebene durableStateStore funktioniert weiterhin und liefert dieselbe
Instanz; sie wird nur gebaut, wenn sie zum ersten Mal angefragt wird, statt bei
der Registrierung, wer sie also lieber im Code an einen DurableStateActor
übergibt, macht genau das weiter — ein Plug-in behält sie, indem es das
Ergebnis zuweist,
(persistence) => { mongo = registerMongoPlugins(persistence, registerOptions); }.
Ein von Hand verdrahteter Store ist allerdings kein ausgewählter, er öffnet also
bei der ersten Verwendung statt mit dem Start.
Aus HOCON konfigurieren
Abschnitt betitelt „Aus HOCON konfigurieren“Die Plugin-Id ist der Config-Abschnitt: Der Block, der nach der Id benannt
ist, ist der Block, den dieses Plugin liest (#872). Alles außer den lebenden
Objekten kann aus der application.conf kommen, registerMongoPlugins(persistence) braucht damit
gar keine Optionen mehr:
import { ActorSystem, ActorSystemOptions } from 'actor-ts';import { registerMongoPlugins } from 'actor-ts/persistence';
const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [(persistence) => registerMongoPlugins(persistence)],});const system = ActorSystem.create('my-app', systemOptions);actor-ts.persistence { journal { plugin = "actor-ts.persistence.journal.mongodb" } snapshot-store { plugin = "actor-ts.persistence.snapshot-store.mongodb" } durable-state { plugin = "actor-ts.persistence.durable-state.mongodb" }
journal.mongodb { url = ${?MONGO_URL}, database-name = "app", events-collection = "events" } snapshot-store.mongodb { url = ${?MONGO_URL}, database-name = "app", keep-n = 5 } durable-state.mongodb { url = ${?MONGO_URL}, database-name = "app", collection = "durable_state" }}Die Blätter heißen collection, nicht table, und der Schalter heißt
auto-create-indexes statt auto-create-tables — der Block spricht Mongos
Vokabular, denn ein Blatt, das nach dem Vokabular eines anderen Backends benannt
ist, muss man beim Lesen übersetzen. Die Verbindung steht unter allen drei
Wurzeln statt einmal darüber: Eine Plugin-Id ist ihr Config-Abschnitt, und die
drei Achsen werden unabhängig gewählt, dürfen also legitim verschiedene
Deployments benennen. Wer nur eines hat, schreibt sie einmal und substituiert.
An registerMongoPlugins übergebene Optionen gewinnen weiterhin, Feld für Feld,
und ein nicht gesetztes Feld fällt auf den Block durch, statt ihn zu leeren — ein
geteilter client im Code und die Collection-Namen in HOCON sind also eine
normale Mischung. Ein vorab gebauter client und ein serializer haben gar
kein Blatt: Das sind lebende Objekte, die eine Config-Datei nicht ausdrücken
kann. clientOptions ebenso wenig — die ganze Optionsfläche des Treibers, die
code-only bleibt.
Was du am Client tatsächlich einstellst, hat typisierte Blätter (#1490), jedes als Kommentar in der Referenzkonfiguration, damit Weglassen den eigenen Default des Treibers behält:
actor-ts.persistence.journal.mongodb { url = ${?MONGO_URL} max-pool-size = 50 # the driver's maxPoolSize (default 100) min-pool-size = 5 # minPoolSize (default 0) server-selection-timeout = 10s # serverSelectionTimeoutMS (default 30s) connect-timeout = 5s # connectTimeoutMS (default 30s) ca-file = "/etc/ssl/mongo-ca.pem" # read when the client opens, handed over as ca}Jedes erreicht den Treiber nur, wenn es gesetzt ist, unter dem eigenen Namen des
Treibers. Der Store prüft sie beim Bauen: Eine Pool-Größe oder ein Timeout, das
keine positive ganze Zahl ist (eine Mindest-Pool-Größe von 0, der Default, ist
in Ordnung), ein Minimum über dem Maximum oder ein Timeout, das länger ist, als
ein Timer halten kann, wird mit einem OptionsError abgelehnt. Ebenso ein Blatt
neben derselben Option in clientOptions oder in der Query der URL
(max-pool-size neben maxPoolSize=20 etwa), und zwar unter Nennung beider
Seiten: Der Treiber liest alle drei ohne Rücksicht auf Groß- und Kleinschreibung,
behält den Wert des Objekts und verwirft den der URL kommentarlos, also verlangt
der Store, dass du es an einer Stelle setzt. ca-file ist ein Pfad, den das
Framework liest, nie das Zertifikat selbst; eine Datei, die es nicht lesen kann,
lässt das Öffnen des Stores fehlschlagen — den Start, oder seine erste
Benutzung, wenn das Öffnen beim Start abgeschaltet ist — und nennt dabei Blatt
und Pfad.
Eine url, die die TLS-Verifizierung abschaltet, wird abgelehnt.
tlsInsecure, tlsAllowInvalidCertificates oder tlsAllowInvalidHostnames
auf irgendetwas außer false gesetzt, lässt den Reader einen ConfigError
werfen, der Blatt und Schalter nennt, in jeder Groß- und Kleinschreibung des
Schlüssels und gleich, ob die URL ausgeschrieben oder aus ${?MONGO_URL}
substituiert ist. Für die Datei ist die Ablehnung strikt: Die url des Blocks
wird auch dann abgelehnt, wenn registerMongoPlugins eine eigene URL oder einen
eigenen Client bekommt. Inspiziert wird nur HOCON — derselbe String, an
withUrl(...) übergeben, und clientOptions sind die Entscheidung deines
Codes. Eine private CA braucht gar keinen Code: Nenne ihre Datei mit dem Blatt
ca-file des Blocks, das das Framework liest und mit eingeschaltetem TLS
übergibt, oder mit tls=true&tlsCAFile=<CA-Datei> in der URL, das der Treiber
selbst liest. Das eine oder das andere: Der Treiber liest tlsCAFile nur, wenn
keine CA übergeben wurde, also wird ca-file daneben abgelehnt, statt eines von
beiden stillschweigend fallen zu lassen. tls=false ist Klartext statt
unverifiziertem TLS und bleibt erlaubt — nur nicht neben ca-file, das es
ungenutzt ließe.
Ist ca-file gesetzt, wird auch der Code daran gehalten. Der Store lehnt das
Blatt beim Bauen mit einem OptionsError ab, der beide Seiten nennt: neben
einem ca oder einem tlsCAFile in clientOptions; neben einem tls, ssl,
tlsInsecure oder tlsAllowInvalidCertificates dort, das die CA ungenutzt
ließe; neben einem rejectUnauthorized mit false, in jeder Schreibweise des
Schlüssels, also dem Schalter, den tlsInsecure setzt; und neben einem
secureContext, das einen eigenen Trust-Store mitbringt, der statt der CA
benutzt wird. Auch ein vorgebauter client neben ca-file wird abgelehnt: Er
wurde dort konfiguriert, wo er gebaut wurde, und liest das Blatt nie — gib
diesem Client seine CA, oder übergib stattdessen url. Die Begründung steht
unter TLS everywhere.
Einen Client teilen
Abschnitt betitelt „Einen Client teilen“Ein MongoClient ist selbst schon ein Connection-Pool; einen zu übergeben ist
daher die effiziente Variante, wenn alle Komponenten dasselbe Deployment
adressieren:
import { MongoClient } from 'mongodb';
const client = new MongoClient('mongodb://localhost:27017');await client.connect();const registerMongoPluginsOptions = RegisterMongoPluginsOptions.create() .withClient(client) .withDatabaseName('app');const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [(persistence) => registerMongoPlugins(persistence, registerMongoPluginsOptions)],});Ein geteilter Client gehört dem Caller: kein Store schließt ihn, du schließt
ihn also selbst beim Shutdown. Übergib stattdessen url, dann baut jeder Store
seinen eigenen Client und schließt ihn bei close(). Jeder Store erreicht das
Deployment beim Öffnen trotzdem, über den geteilten Client — sein Ping nimmt
diesen Weg —, und keiner von ihnen nimmt ca-file daneben an: Konfiguriere
das TLS des Clients dort, wo du ihn baust.
Wann du es einsetzt
Abschnitt betitelt „Wann du es einsetzt“- MongoDB ist schon deine Datenbank. Der größte Treiber im Ökosystem und derjenige, den viele Teams ohnehin betreiben.
- Du willst indizierte Tag-Queries. Nur MongoDB, SQLite/libSQL und Cassandra
drücken
currentEventsByTagin den Storage hinunter; die relationalen Backends pollen. - Du willst ein Deployment für Events und Read-Models. Projections können ihre Views in dieselbe Datenbank schreiben.
Konfiguration
Abschnitt betitelt „Konfiguration“type MongoConnection = { url?: string; // mongodb:// or mongodb+srv:// databaseName?: string; // default 'actor_ts' clientOptions?: Record<string, unknown>; // extra MongoClient options — the code-only long tail client?: MongoClientLike; // pre-built / shared client maxPoolSize?: number; // maxPoolSize, default 100 (max-pool-size) minPoolSize?: number; // minPoolSize, default 0 (min-pool-size) serverSelectionTimeoutMs?: number; // serverSelectionTimeoutMS, 30 000 (server-selection-timeout) connectTimeoutMs?: number; // connectTimeoutMS, 30 000 (connect-timeout) caFile?: string; // PEM file read into ca, with tls on (ca-file)};
interface MongoJournalOptions extends MongoConnection { eventsCollection?: string; // default 'events'; its mark collection is '<it>_meta' autoCreateIndexes?: boolean; // default true}interface MongoSnapshotStoreOptions extends MongoConnection { snapshotsCollection?: string; // default 'snapshots' keepN?: number; // keep newest N per pid; default 3, <=0 keeps all autoCreateIndexes?: boolean;}interface MongoDurableStateStoreOptions extends MongoConnection { collection?: string; // default 'durable_state'}Die Optionen werden bei der Konstruktion des Stores validiert — ein falsches
URL-Schema oder ein Datenbankname, den MongoDB ablehnen würde (mit /, \, .,
" oder Leerzeichen), schlägt beim Verdrahten fehl, nicht erst beim ersten
Schreiben. Eine Seed-Liste für ein Replica Set ohne SRV, etwa
mongodb://h1:27017,h2:27017,h3:27017/app?replicaSet=rs, wird angenommen, wie
der Treiber sie annimmt; eine mongodb+srv://-URL nennt dagegen genau einen
Host und keinen Port, weil DNS die Mitglieder liefert.
Collections und Indizes
Abschnitt betitelt „Collections und Indizes“| Collection | Shape | Index |
|---|---|---|
events | { persistenceId, sequenceNr, payload, tags?, timestamp } | unique (persistenceId, sequenceNr); (tags, timestamp) |
events_meta | { _id: persistenceId, deletedTo } | _id |
snapshots | { persistenceId, sequenceNr, payload, timestamp } | unique (persistenceId, sequenceNr) |
durable_state | { _id: persistenceId, revision, payload, timestamp } | _id |
Concurrency-Modell
Abschnitt betitelt „Concurrency-Modell“- Journal-Append liest den aktuellen Head und fügt dann ein. Der Unique-
Compound-Index weist einen konkurrierenden Writer mit Serverfehler 11000
ab, der in einen
JournalConcurrencyErrorübersetzt wird — dasselbe zweischichtige Schema wie bei den SQL-Backends (Head-Prüfung für den Normalfall, konditionaler Write für das Rennen), mit Fehler 11000 in der Rolle von SQLSTATE23505. - Durable-State-CAS steckt die Revision in den Filter:
updateOne({ _id, revision: expected }, …). Eine Abweichung matcht nichts,matchedCount === 0heißt also, dass die gespeicherte Revision abgewichen ist. Ein Create istinsertOne, wo_iddas Duplikat abweist. - Die Kompaktierungs-Marke ist monoton über
$max, das nur schreibt, wenn der neue Wert größer ist — genau das, wasGREATESTin den SQL-Dialekten tut.
Keine Transaktionen nötig
Abschnitt betitelt „Keine Transaktionen nötig“MongoDBs Multi-Document-Transaktionen brauchen ein Replica Set, und dieses
Backend nutzt sie bewusst nicht — es läuft daher auf einem Standalone-mongod.
Das ist begründet, nicht Glück. Appends sind vom Head aus lückenlos, zwei
Writer, die sich über den Head einig sind, versuchen also dieselbe erste
Sequenznummer: das insertMany des Verlierers scheitert an seinem allerersten
Dokument, und ordered: true bricht den Batch dort ab — er schreibt nichts. Ein
partieller Append ist über Contention also nicht erreichbar, und genau das wäre
das Einzige gewesen, was eine Transaktion gebracht hätte.
Tag-Queries
Abschnitt betitelt „Tag-Queries“MongoQuery gibt currentEventsByTag einen indizierten Pfad. Weil tags ein
Array ist, indiziert MongoDB es als Multikey-Index — ein Eintrag pro Tag pro
Event — eine Query auf einen Tag plus eine Timestamp-Untergrenze läuft damit
einen zusammenhängenden Bereich ab statt zu scannen:
import { MongoQuery, offsetStart } from 'actor-ts/persistence';
const query = new MongoQuery(journal);const tagged = await query.currentEventsByTag({ all: ['ledger'], not: ['audit'] }, offsetStart);Der Server vorfiltert auf einen Tag; all jenseits des ersten Tags,
Cross-Tag-any und not werden im Speicher verfeinert, genau wie in den
SQLite- und Cassandra-Pfaden. Ein Filter mit nur not hat nichts zum
Vorfiltern und fällt auf den Journal-Scan zurück.
Fallstricke
Abschnitt betitelt „Fallstricke“Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- PostgreSQL — das relationale Gegenstück, mit transaktionalen Multi-Event-Appends.
- Cassandra-Journal — der andere verteilte Store mit indiziertem Tag-Pfad.
- Durable State — die State-orientierte Alternative zum Event-Sourcing.
- Snapshots — begrenzt den Recovery-Scan.
