PostgreSQL
Das Postgres-Backend liefert alle drei Persistence-Komponenten gegen eine
einzige PostgreSQL-Datenbank, über den
pg-Treiber:
PostgresJournal— das Event-Journal fürPersistentActors.PostgresSnapshotStore— Snapshots, um die Recovery zu begrenzen.PostgresDurableStateStore— Key-Value-Durable-State fürDurableStateActors. Das ist der erste SQL-basierte Durable-State-Store (SQLite und Cassandra liefern nur Journal + Snapshot).
Wie Cassandra ist Postgres über Cluster-Nodes geteilt — jeder Node kann jede persistenceId lesen/schreiben — aber relational, transaktional und mit ziemlicher Sicherheit schon in deinem Stack.
Installation
Abschnitt betitelt „Installation“pg ist eine optionale Peer-Dependency — installiere sie neben actor-ts:
bun add pgDas Framework importiert pg erst, wenn ein Postgres-Store öffnet — beim
Start, oder bei der ersten Verwendung, wenn das Öffnen beim Start
abgeschaltet ist —, hält es also bis zum Opt-in aus deinem Bundle.
Einrichtung
Abschnitt betitelt „Einrichtung“Registriere alle drei Stores über den plugins-Slot der Optionen des
Systems und wähle sie in seiner Konfiguration aus. Gib einen geteilten
pool mit, damit alle drei Komponenten einen Connection-Pool nutzen:
import { Pool } from 'pg';import { ActorSystem, ActorSystemOptions,} from 'actor-ts';import { PostgresJournalOptions, PostgresSnapshotStoreOptions, PostgresDurableStateStoreOptions, RegisterPostgresPluginsOptions, registerPostgresPlugins,} from 'actor-ts/persistence';
const postgresSnapshotStoreOptions = PostgresSnapshotStoreOptions.create().withKeepN(3);const registerOptions = RegisterPostgresPluginsOptions.create() // One pool shared by journal + snapshot + durable-state (recommended). .withPool(new Pool({ connectionString: 'postgres://user:pass@host:5432/app' })) .withJournal(PostgresJournalOptions.create() /* .withEventsTable(...).withTagsTable(...).withAutoCreateTables(...) */) .withSnapshotStore(postgresSnapshotStoreOptions) .withDurableStateStore(PostgresDurableStateStoreOptions.create() /* .withTable(...) */);const systemOptions = ActorSystemOptions.create() // Select the Postgres plugins for all three stores. .withConfig({ 'actor-ts': { persistence: { journal: { plugin: 'actor-ts.persistence.journal.postgres' }, 'snapshot-store': { plugin: 'actor-ts.persistence.snapshot-store.postgres' }, 'durable-state': { plugin: 'actor-ts.persistence.durable-state.postgres' }, }, }, }) .withPersistence({ plugins: [(persistence) => registerPostgresPlugins(persistence, registerOptions)] });const system = ActorSystem.create('my-app', systemOptions);Das Plug-in läuft innerhalb von ActorSystem.create, also sind alle drei
Stores registriert, bevor create zurückkehrt, und die, die die
Konfiguration auswählt, öffnen als Teil des Starts: Eine Datenbank, die der
Knoten nicht erreicht, lässt den Start scheitern statt erst die erste
persistierte Nachricht — siehe Stores beim Start
öffnen.
Das gilt auch mit autoCreateTables: false, weil das Öffnen dann ein
SELECT 1 schickt, wo es sonst das DDL ausführen würde, und solange das
Öffnen beim Start an ist, der Default: Ist das Öffnen beim Start abgeschaltet,
wandert der Fehler zur ersten Operation des Stores. 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.
registerPostgresPlugins gibt außerdem den Durable-State-Store
zurück, falls du ihn lieber von Hand verdrahtest; ein Plug-in behält ihn,
indem es das Ergebnis zuweist,
(persistence) => { postgres = registerPostgresPlugins(persistence, registerOptions); }.
Seit #872 ist das eine Bequemlichkeit und nicht mehr der einzige Weg, und ein
von Hand verdrahteter Store ist kein ausgewählter, er öffnet also bei der
ersten Verwendung statt mit dem Start.
Ohne geteilten pool baut jede Komponente ihren eigenen Pool aus
url / poolConfig, wenn sie öffnet:
const postgresJournalOptions = PostgresJournalOptions.create().withUrl('postgres://user:pass@host:5432/app');const postgresSnapshotStoreOptions = PostgresSnapshotStoreOptions.create() .withUrl('postgres://user:pass@host:5432/app').withKeepN(3);const postgresDurableStateStoreOptions = PostgresDurableStateStoreOptions.create().withUrl('postgres://user:pass@host:5432/app');const registerPostgresPluginsOptions = RegisterPostgresPluginsOptions.create() .withJournal(postgresJournalOptions) .withSnapshotStore(postgresSnapshotStoreOptions) .withDurableStateStore(postgresDurableStateStoreOptions);const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [(persistence) => registerPostgresPlugins(persistence, registerPostgresPluginsOptions)],});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, registerPostgresPlugins(persistence) braucht damit
gar keine Optionen mehr:
import { ActorSystem, ActorSystemOptions } from 'actor-ts';import { registerPostgresPlugins } from 'actor-ts/persistence';
const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [(persistence) => registerPostgresPlugins(persistence)],});const system = ActorSystem.create('my-app', systemOptions);actor-ts.persistence { journal { plugin = "actor-ts.persistence.journal.postgres" } snapshot-store { plugin = "actor-ts.persistence.snapshot-store.postgres" } durable-state { plugin = "actor-ts.persistence.durable-state.postgres" }
journal.postgres { url = ${?DATABASE_URL}, events-table = "events" } snapshot-store.postgres { url = ${?DATABASE_URL}, keep-n = 5 } durable-state.postgres { url = ${?DATABASE_URL}, table = "durable_state" }}An registerPostgresPlugins ü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 Pool im Code und die Tabellennamen in HOCON sind also eine
normale Mischung. Ein vorab gebauter Pool und ein serializer haben
gar kein Blatt: Das sind lebende Objekte, die eine Config-Datei nicht
ausdrücken kann. poolConfig ebenso wenig — die gesamte Optionsfläche des
Treibers, die code-only bleibt. tags-table wird gelesen, wird aber als
Kommentar statt als Schlüssel ausgeliefert, weil sein Default aus
events-table abgeleitet wird und genau die Abwesenheit beide im Gleichlauf
hält.
Was du am Pool tatsächlich einstellst, hat typisierte Blätter (#1490), jedes in der Referenzkonfiguration nur als Kommentar, damit Weglassen den eigenen Default von pg behält:
actor-ts.persistence.journal.postgres { url = ${?DATABASE_URL} max-pool-size = 20 # pg-pool's max (default 10) idle-timeout = 30s # pg-pool's idleTimeoutMillis (default 10s) connect-timeout = 5s # pg's connectionTimeoutMillis (default: none) ca-file = "/etc/ssl/rds-ca.pem" # read when the pool opens, handed to pg as ssl.ca}Jedes erreicht den Treiber nur, wenn es gesetzt ist. Der Store prüft sie beim
Bau: eine Größe oder ein Timeout, das keine positive ganze Zahl ist, oder ein
Timeout, länger als ein Timer halten kann, wird mit einem OptionsError
abgelehnt — ebenso ein Blatt neben demselben Schlüssel in poolConfig
(max-pool-size neben max etwa), das dann beide nennt, statt eine Seite still
gewinnen zu lassen. 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 scheitern — den Start, oder seine erste Nutzung, wenn das Öffnen beim
Start abgeschaltet ist — und nennt Blatt und Pfad.
Eine url, die die TLS-Verifizierung abschaltet, wird abgelehnt.
sslmode=no-verify, ssl=no-verify und — unter uselibpqcompat=true —
sslmode=prefer, require oder verify-ca lassen den Reader einen
ConfigError werfen, der Blatt und Schalter nennt, in jeder Groß- und
Kleinschreibung und gleich, ob die URL ausgeschrieben oder aus
${?DATABASE_URL} substituiert ist. Für die Datei ist die Ablehnung strikt:
Die url des Blocks wird auch dann abgelehnt, wenn registerPostgresPlugins
eine eigene URL oder einen eigenen Pool bekommt. Inspiziert wird nur HOCON —
derselbe String, an withUrl(...) übergeben, ist die Entscheidung deines Codes,
und dort gehört ein unverifizierter Server hin, wenn du wirklich einen meinst.
Für eine private CA setzt du ca-file und lässt die ssl-Parameter der URL weg,
oder du schreibst sslmode=verify-full&sslrootcert=<CA-Datei> — eins von
beiden: node-postgres legt die TLS-Einstellungen, die es aus der URL parst, über
die ihm übergebenen, deshalb wird ca-file neben irgendeinem ssl-Parameter der
URL abgelehnt statt verworfen. sslmode=disable ist Klartext statt
unverifiziertem TLS und bleibt erlaubt. Die Begründung und die Schalter
vollständig stehen unter
TLS everywhere.
durable-state.plugin wählt jetzt den Durable-State-Store dieses Backends
aus. Früher wurde er eifrig gebaut und von registerPostgresPlugins zurückgegeben, ließ
sich also nur verdrahten, indem man diese Instanz durch den Anwendungscode
reichte. Das zurückgegebene Handle funktioniert weiterhin und liefert dieselbe
Instanz — sie wird nur gebaut, wenn sie zum ersten Mal angefragt wird, statt
bei der Registrierung, und bei einem ausgewählten Store ist das der Start.
Wann einsetzen
Abschnitt betitelt „Wann einsetzen“- Du betreibst ohnehin Postgres. Ein bewegliches Teil weniger als ein Cassandra-Aufbau — nutze deine bestehende Managed-Instanz (RDS, Cloud SQL, Supabase, …).
- Cluster-geteilte Persistence. Geshardete Entities, die zwischen Nodes wandern, oder Cross-Node-Projektionen brauchen ein Journal, das jeder Node lesen kann.
- Du willst Durable-State in SQL. Der einzige SQL-Durable-State-Store im Framework.
Für Single-Node-Entwicklung ist SqliteJournal
einfacher (eine Datei, kein Server).
Konfiguration
Abschnitt betitelt „Konfiguration“type PostgresConnection = { url?: string; // postgres://user:pass@host:5432/db poolConfig?: Record<string, unknown>; // extra pg.Pool config — the code-only long tail pool?: PgPoolLike; // pre-built / shared pool maxPoolSize?: number; // pg-pool max, default 10 (max-pool-size) idleTimeoutMs?: number; // idleTimeoutMillis, default 10 000 (idle-timeout) connectTimeoutMs?: number; // connectionTimeoutMillis, no limit (connect-timeout) caFile?: string; // PEM file read into ssl.ca (ca-file)};
interface PostgresJournalOptions extends PostgresConnection { eventsTable?: string; // default 'events' tagsTable?: string; // default '<eventsTable>_tags' autoCreateTables?: boolean; // default true}interface PostgresSnapshotStoreOptions extends PostgresConnection { snapshotsTable?: string; // default 'snapshots' keepN?: number; // keep newest N per pid; default 3, <=0 keeps all autoCreateTables?: boolean;}interface PostgresDurableStateStoreOptions extends PostgresConnection { table?: string; // default 'durable_state' autoCreateTables?: boolean;}Tabellennamen stammen aus der Config (nicht aus User-Input) und werden
gegen ein Safe-Identifier-Muster geprüft; alles andere — persistenceIds,
Tags, Payloads — geht als Bind-Parameter ($1, $2, …), nie per
String-Concat.
Die Verbindung wird beim Bau des Stores validiert, und eine Kombination, die
bisher durchging, wird abgelehnt: ein poolConfig.ssl neben einer URL (oder
einem poolConfig.connectionString) mit ssl-Parameter. node-postgres legt die
TLS-Einstellungen, die es aus dem Connection-String parst, über das
Config-Objekt, das ssl-Objekt wurde also nie zusammengeführt, sondern
ersetzt — gegen den Treiber ausgeführt, fiel eine CA neben sslmode=verify-full
weg, und neben sslmode=no-verify ging die Verifizierung mit ihr aus.
Konfiguriere TLS an einer der beiden Stellen.
Mit autoCreateTables (Default) führt das Backend
CREATE TABLE IF NOT EXISTS aus, wenn der Store öffnet — beim Start, oder
bei der ersten Verwendung, wenn das Öffnen beim Start abgeschaltet ist:
CREATE TABLE events ( persistence_id TEXT NOT NULL, sequence_nr BIGINT NOT NULL, payload TEXT NOT NULL, -- JSON tags TEXT, -- CSV (auch in events_tags gespiegelt) timestamp BIGINT NOT NULL, PRIMARY KEY (persistence_id, sequence_nr));CREATE TABLE events_tags ( -- indizierte Tag-Lookups für Projektionen persistence_id TEXT NOT NULL, sequence_nr BIGINT NOT NULL, tag TEXT NOT NULL, timestamp BIGINT NOT NULL, PRIMARY KEY (tag, timestamp, persistence_id, sequence_nr));CREATE TABLE snapshots ( persistence_id TEXT NOT NULL, sequence_nr BIGINT NOT NULL, payload TEXT NOT NULL, timestamp BIGINT NOT NULL, PRIMARY KEY (persistence_id, sequence_nr));CREATE TABLE durable_state ( persistence_id TEXT PRIMARY KEY, revision BIGINT NOT NULL, payload TEXT NOT NULL, timestamp BIGINT NOT NULL);Lege die Tabellen vorab an (und vergib nur INSERT/SELECT/UPDATE/DELETE)
und setze autoCreateTables: false, wenn deine DB-Rolle kein DDL darf. Ist
es aus, schickt der Store ein SELECT 1, wo er sonst das DDL ausführen würde,
und erreicht die Datenbank also trotzdem, wenn er öffnet.
Tag-Queries
Abschnitt betitelt „Tag-Queries“events_tags ist der Index hinter den By-Tag-Methoden von
PersistenceQuery. Sein Primärschlüssel beginnt mit
(tag, timestamp, …), ein By-Tag-Read läuft also einen zusammenhängenden
Bereich dieses Index ab und joint anschließend für das Payload zurück auf
events — die Kosten hängen an der Historie des Tags, nicht an der des
Journals.
Gelesen wird er von PostgresQuery. Umschließe damit die
Journal-Instanz, in die deine Aktoren schreiben, und übergib die Query
einer Projektion — die übrigen Felder stehen unter
Projektionen:
import { PostgresJournal, PostgresJournalOptions, PostgresQuery } from 'actor-ts/persistence';
const journalOptions = PostgresJournalOptions.create().withUrl(process.env.DATABASE_URL!);const eventsJournal = new PostgresJournal(journalOptions);const query = new PostgresQuery(eventsJournal);Drei Filterformen, drei Pläne:
| Filter | Was läuft |
|---|---|
'type:Order' / { all: [...] } | Index-Bereichslauf auf dem ersten Tag, die übrigen Operatoren werden im Prozess nachgefiltert |
{ any: [...] } | t.tag IN (…) mit DISTINCT, damit ein Event mit mehreren der genannten Tags nur einmal zurückkommt |
{ not: [...] } allein | kein selektives Tag als Startpunkt — fällt auf den Journal-Scan zurück |
Stattdessen zu InMemoryQuery zu greifen ist nicht falsch, nur langsam:
sie spielt bei jedem Poll jede Persistence-Id erneut ab. Siehe
Persistence Query.
Concurrency-Modell
Abschnitt betitelt „Concurrency-Modell“- Journal-Append führt
SELECT MAX(sequence_nr)und die Inserts in EINER Transaktion aus; dasexpectedSeqdes Callers wird gegen den aktuellen Head geprüft. Ein durchrutschender konkurrierender Writer verletzt den Primary-Key-Unique-Constraint (SQLSTATE23505), was als Backstop inJournalConcurrencyErrorübersetzt wird. Bricht die Engine den Verlierer vor der Key-Prüfung wegen Contention ab (40001/40P01— beiSERIALIZABLEerreichbar und auf den wire-kompatiblen Engines der Normalfall), gilt dasselbe, aber erst wenn ein erneutes Lesen bestätigt, dass der Head sich bewegt hat: ein gewöhnliches Lock-Problem bleibt einJournalError, statt zur Retry-Schleife zu werden. - Durable-State-CAS nutzt die
revision-Spalte: Anlegen (expectedRevision === 0) istINSERT … ON CONFLICT DO NOTHING, ein Update istUPDATE … WHERE revision = expected. Null betroffene Zeilen ⇒DurableStateConcurrencyError, mit der aktuellen Revision für den Caller zurückgelesen.
BIGINT-Spalten liefert pg als Strings; das Backend coerct
sequence_nr / revision / timestamp an der Mapping-Grenze zu
number.
Fallstricke
Abschnitt betitelt „Fallstricke“Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- MariaDB — das Geschwister aus der MySQL-Familie.
- Cassandra-Journal — verteilt, für Skalierung jenseits einer einzelnen relationalen Instanz.
- SQLite-Journal — Single-Node, kein Server.
- Durable State — die State-orientierte Alternative zum Event Sourcing.
- Snapshots — den Recovery-Scan begrenzen.
