Zum Inhalt springen
Deutsch

PostgreSQL

Das Postgres-Backend liefert alle drei Persistence-Komponenten gegen eine einzige PostgreSQL-Datenbank, über den pg-Treiber:

  • PostgresJournal — das Event-Journal für PersistentActors.
  • PostgresSnapshotStore — Snapshots, um die Recovery zu begrenzen.
  • PostgresDurableStateStore — Key-Value-Durable-State für DurableStateActors. 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.

pg ist eine optionale Peer-Dependency — installiere sie neben actor-ts:

Terminal-Fenster
bun add pg

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

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)],
});

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.

  • 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).

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.

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:

FilterWas 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: [...] } alleinkein 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.

  • Journal-Append führt SELECT MAX(sequence_nr) und die Inserts in EINER Transaktion aus; das expectedSeq des Callers wird gegen den aktuellen Head geprüft. Ein durchrutschender konkurrierender Writer verletzt den Primary-Key-Unique-Constraint (SQLSTATE 23505), was als Backstop in JournalConcurrencyError übersetzt wird. Bricht die Engine den Verlierer vor der Key-Prüfung wegen Contention ab (40001 / 40P01 — bei SERIALIZABLE erreichbar 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 ein JournalError, statt zur Retry-Schleife zu werden.
  • Durable-State-CAS nutzt die revision-Spalte: Anlegen (expectedRevision === 0) ist INSERT … ON CONFLICT DO NOTHING, ein Update ist UPDATE … 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.

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