MariaDB
Das MariaDB-Backend ist das Geschwister des
Postgres-Backends für Teams auf
MariaDB oder MySQL. Es liefert dieselben drei Komponenten —
MariaDbJournal, MariaDbSnapshotStore und
MariaDbDurableStateStore — gegen eine einzige Datenbank, über den
offiziellen
mariadb-Connector
(der sowohl MariaDB als auch MySQL spricht).
Es ist eine eigenständige Implementierung (kein geteilter Dialekt-Layer), also ist das SQL idiomatisches MariaDB — der öffentliche Vertrag und das Verhalten sind aber identisch.
Installation
Abschnitt betitelt „Installation“mariadb ist eine optionale Peer-Dependency:
bun add mariadbImportiert, wenn ein MariaDB-Store öffnet — beim Start, oder bei der ersten Verwendung, wenn das Öffnen beim Start abgeschaltet ist —, wie jeder andere Adapter.
Einrichtung
Abschnitt betitelt „Einrichtung“import { ActorSystem, ActorSystemOptions,} from 'actor-ts';import { MariaDbJournalOptions, MariaDbSnapshotStoreOptions, MariaDbDurableStateStoreOptions, RegisterMariaDbPluginsOptions, registerMariaDbPlugins,} from 'actor-ts/persistence';
const mariaDbJournalOptions = MariaDbJournalOptions.create().withPoolConfig(connection);const mariaDbSnapshotStoreOptions = MariaDbSnapshotStoreOptions.create() .withPoolConfig(connection) .withKeepN(3);const mariaDbDurableStateStoreOptions = MariaDbDurableStateStoreOptions.create().withPoolConfig(connection);const registerMariaDbPluginsOptions = RegisterMariaDbPluginsOptions.create() .withJournal(mariaDbJournalOptions) .withSnapshotStore(mariaDbSnapshotStoreOptions) .withDurableStateStore(mariaDbDurableStateStoreOptions);const actorSystemOptions = ActorSystemOptions.create() .withConfig({ 'actor-ts': { persistence: { journal: { plugin: 'actor-ts.persistence.journal.mariadb' }, 'snapshot-store': { plugin: 'actor-ts.persistence.snapshot-store.mariadb' }, 'durable-state': { plugin: 'actor-ts.persistence.durable-state.mariadb' }, }, }, }) .withPersistence({ plugins: [(persistence) => registerMariaDbPlugins(persistence, registerMariaDbPluginsOptions)] });const system = ActorSystem.create('my-app', actorSystemOptions);
// connection = { host, port: 3306, user, password, database } — or pass a// shared `pool` (from mariadb.createPool) at the top level via// `.withPool(pool)` to reuse one pool across all three, or a connection// URL via `.withUrl(...)`.Wie bei Postgres läuft das Plug-in innerhalb von ActorSystem.create, und
die Konfiguration wählt alle drei Stores aus, die als Teil des Starts
öffnen: Eine Datenbank, die der Knoten nicht erreicht, lässt den Start
scheitern statt erst die erste persistierte Nachricht, ob
autoCreateTables an ist oder aus — siehe Stores beim Start
öffnen.
Der Durable-State-Store wird außerdem zurückgegeben, falls du ihn lieber
von Hand in die Settings deines DurableStateActor reichst; ein so
verdrahteter Store ist 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, registerMariaDbPlugins(persistence) braucht damit
gar keine Optionen mehr:
import { ActorSystem, ActorSystemOptions } from 'actor-ts';import { registerMariaDbPlugins } from 'actor-ts/persistence';
const systemOptions = ActorSystemOptions.create().withPersistence({ plugins: [(persistence) => registerMariaDbPlugins(persistence)],});const system = ActorSystem.create('my-app', systemOptions);actor-ts.persistence { journal { plugin = "actor-ts.persistence.journal.mariadb" } snapshot-store { plugin = "actor-ts.persistence.snapshot-store.mariadb" } durable-state { plugin = "actor-ts.persistence.durable-state.mariadb" }
journal.mariadb { url = ${?DATABASE_URL}, events-table = "events" } snapshot-store.mariadb { url = ${?DATABASE_URL}, keep-n = 5 } durable-state.mariadb { url = ${?DATABASE_URL}, table = "durable_state" }}An registerMariaDbPlugins ü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
Connectors, 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 des Connectors behält:
actor-ts.persistence.journal.mariadb { url = ${?DATABASE_URL} max-pool-size = 20 # connectionLimit (default 10) acquire-timeout = 5s # acquireTimeout (default 10s) idle-timeout = 10m # idleTimeout, whole seconds only (default 1800s) connect-timeout = 2s # connectTimeout (default 1s) ca-file = "/etc/ssl/maria-ca.pem" # read when the pool opens, handed over as ssl.ca}Jedes erreicht den Connector nur, wenn es gesetzt ist — über die URL gelegt, die
so geparst wird, wie der Connector sie parst, damit ihr Host, ihre Datenbank und
ihre Optionen erhalten bleiben. Der Store prüft sie beim Bau: eine Größe oder
ein Timeout, das keine positive ganze Zahl ist, ein idle-timeout, das keine
ganze Zahl von Sekunden ist (der Connector zählt es in Sekunden), oder ein
Timeout, länger als ein Timer halten kann, wird mit einem OptionsError
abgelehnt — ebenso ein Blatt neben derselben Option in poolConfig oder in der
Query der URL (max-pool-size neben connectionLimit= 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, und der einzige Weg zu einer
privaten CA aus der Konfiguration: Das ssl der URL ist ein bloßer Schalter.
Abgelehnt wird es neben einem ssl in der URL, das der Connector als false
liest — alles außer genau true, also auch ssl=TRUE —, weil das TLS
abschaltet.
durable-state.plugin wählt jetzt den Durable-State-Store dieses Backends
aus. Früher wurde er eifrig gebaut und von registerMariaDbPlugins 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.
Konfiguration
Abschnitt betitelt „Konfiguration“type MariaDbConnection = { url?: string; // mariadb://user:pass@host:3306/db poolConfig?: Record<string, unknown>; // { host, port, user, password, database, … } pool?: MariaDbPoolLike; // pre-built / shared pool maxPoolSize?: number; // connectionLimit, default 10 (max-pool-size) acquireTimeoutMs?: number; // acquireTimeout, default 10 000 (acquire-timeout) idleTimeoutMs?: number; // idleTimeout in whole s, default 1800 s (idle-timeout) connectTimeoutMs?: number; // connectTimeout, default 1 000 (connect-timeout) caFile?: string; // PEM file read into ssl.ca (ca-file)};interface MariaDbJournalOptions extends MariaDbConnection { eventsTable?: string; tagsTable?: string; autoCreateTables?: boolean;}interface MariaDbSnapshotStoreOptions extends MariaDbConnection { snapshotsTable?: string; keepN?: number; autoCreateTables?: boolean;}interface MariaDbDurableStateStoreOptions extends MariaDbConnection { table?: string; autoCreateTables?: boolean;}Diskretes poolConfig (host/user/password/database) ist der portabelste
Verbindungsweg; url und ein vorgebauter pool werden ebenfalls
akzeptiert. Die Optionen werden beim Bau des Stores validiert — die
MariaDB-Stores hatten keinen Validator, bevor die typisierten
Verbindungsfelder kamen.
Gleiche Form wie bei Postgres,
mit MariaDB-Typen — VARCHAR(255)-Ids, BIGINT für
Sequence/Revision/Timestamp, LONGTEXT-Payloads — und Indizes inline
im CREATE TABLE deklariert (portabel über MariaDB-/MySQL-Versionen,
anders als CREATE INDEX IF NOT EXISTS):
CREATE TABLE events ( persistence_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL, sequence_nr BIGINT NOT NULL, payload LONGTEXT NOT NULL, tags TEXT, timestamp BIGINT NOT NULL, PRIMARY KEY (persistence_id, sequence_nr), INDEX idx_events_pid (persistence_id));-- events_tags, snapshots, durable_state: wie bei Postgres, mit den Typen obenWarum persistence_id und tag kollationiert sind
Abschnitt betitelt „Warum persistence_id und tag kollationiert sind“Jede persistence_id- und tag-Spalte trägt ein explizites COLLATE utf8mb4_bin. Ohne das erbt die Spalte den Server-Standard —
utf8mb4_general_ci auf einer Standard-MariaDB, utf8mb4_0900_ai_ci auf
MySQL 8 — und beide falten Groß-/Kleinschreibung und Akzente.
Eine persistence_id ist nicht bloß ein Wert: sie ist der Name eines
Event-Streams und die Hälfte des events-Primary-Keys. Unter einer
faltenden Kollation sind Alice und alice deshalb ein Stream hier
und zwei auf Postgres, SQLite, MongoDB und DynamoDB. Ein als Alice
gestarteter Actor liest alices Events, faltet sie in seinen eigenen
State und schreibt in alices Stream — ein Cross-Entity-Read, dessen
einziges Symptom eine Serie von JournalConcurrencyErrors ist, die wie
ein Speicherfehler aussieht. Dieselbe Spalte ist der Schlüssel für
Durable-State-Load, Revisions-CAS und Delete; dort überschreibt und löscht
eine Kollision den State einer anderen Entität.
Eine Id-Validierung kann das nicht beheben: Alice und alice sind beide
völlig legale Ids. Was sich unterscheidet, ist der Vergleich, und der
ist eine Eigenschaft der Spalte.
utf8mb4_bin vergleicht Codepoint für Codepoint, so wie es jedes andere
Backend ohnehin tut. Es ist auch die portable Schreibweise —
utf8mb4_0900_bin gibt es nur auf MySQL 8, und MariaDB hatte es nie. Eine
Kollation ohne CHARACTER SET zu nennen legt zugleich den Zeichensatz auf
utf8mb4 fest, statt ihn auf dem Datenbank-Standard zu belassen.
Eine Abweichung bleibt bewusst bestehen: utf8mb4_bin ist PAD SPACE,
also ist 'alice ' hier gleich 'alice', wo Postgres die beiden trennt.
Die NO-PAD-Binärkollationen sind herstellerspezifisch geteilt
(utf8mb4_nopad_bin auf MariaDB, utf8mb4_0900_bin auf MySQL), es gibt
also nichts Portables zum Festlegen — vermeide abschließende Leerzeichen in
Ids, die du selbst erzeugst.
Bestehendes Schema migrieren
Abschnitt betitelt „Bestehendes Schema migrieren“Das DDL ist CREATE TABLE IF NOT EXISTS, und autoCreateTables ist
standardmäßig true — eine bestehende Datenbank übernimmt das also
nicht: das Framework fasst eine vorgefundene Tabelle nie wieder an. Neue
Deployments bekommen die Kollation stillschweigend; eine ältere Datenbank
behält den Server-Standard, bis du die Migration unten ausführst — aber
nicht mehr unbemerkt. Jeder Store liest seine eigenen Tabellen aus
information_schema, wenn er öffnet, und warnt, wenn eine
persistence_id- oder tag-Spalte mit einer nicht-binären Kollation
zurückkommt; er nennt Tabelle, Spalte und die gefundene Kollation. Ein
ausgewählter Store öffnet als Teil des Starts, die Warnung steht also im
Startlog; ist das Öffnen beim Start abgeschaltet, verbindet sich der Store
erst bei Bedarf und warnt beim ersten Zugriff, also bei der ersten
Persistenz-Operation. Dieser Lesezugriff braucht keine
DDL-Rechte und läuft unabhängig davon, ob autoCreateTables gesetzt ist —
denn ein vom Betrieb selbst verwaltetes
Schema ist genau das, das am ehesten älter ist als der Pin. Führe das
einmal pro Datenbank aus, während kein Knoten schreibt:
ALTER TABLE events MODIFY persistence_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL;ALTER TABLE events_tags MODIFY persistence_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL, MODIFY tag VARCHAR(255) COLLATE utf8mb4_bin NOT NULL;ALTER TABLE events_meta MODIFY persistence_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL;ALTER TABLE snapshots MODIFY persistence_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL;ALTER TABLE durable_state MODIFY persistence_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL;MODIFY ersetzt die gesamte Spaltendefinition, NOT NULL muss also
wiederholt werden — lässt du es weg, wird die Spalte stillschweigend
nullable. Die Kollation einer indizierten Spalte zu ändern ist keine
In-Place-Änderung, InnoDB baut jede Tabelle also neu auf: plane einen Lock
für die Dauer und Plattenplatz für eine zweite Kopie ein.
Zwischen den ersten beiden Statements vergleicht der Join der Tag-Queries
eine events-Spalte mit einer events_tags-Spalte anderer Kollation.
MariaDB verweigert das nicht so wie SQL Server: wo eine Seite _bin und die
andere _ci desselben Zeichensatzes ist, gewinnt die _bin-Kollation, der
Join läuft also unter utf8mb4_bin und liefert die richtigen Zeilen — aber
die noch nicht umgestellte Seite kann ihren Index für den Vergleich nicht
nutzen, Tag-Queries sind in diesem Fenster also langsam statt falsch. Eine
tagsTable, die auf eine neue Tabelle neben einem alten events zeigt,
ist dieses Fenster auf Dauer, bis auch events umkollationiert ist.
Die Startwarnung meldet pro Spalte, und genau das unterscheidet diesen
Zustand von einem unangetasteten Schema: startet ein Knoten mitten in der
Migration neu, nennt die Warnung nur die noch offenen Spalten und sagt, dass
das Schema halb migriert ist. Eine tagsTable neben einem alten events
liest sich genauso — bei jedem Öffnen des Stores, bis die Migration fertig
ist.
Prüfe vor der Migration auf Schaden, solange GROUP BY noch die
faltende Kollation benutzt:
SELECT persistence_id, COUNT(DISTINCT persistence_id COLLATE utf8mb4_bin) AS spellings FROM events GROUP BY persistence_idHAVING spellings > 1;Jede Zeile bedeutet, dass sich zwei Ids bereits einen Stream teilen. Das
ALTER trennt sie wieder, und jeder Hälfte fehlen dann die Events der
anderen — diese Actors scheitern beim Recovery also laut mit
JournalIntegrityError (eine Lücke in der Sequenz), statt stillschweigend
eine verschmolzene Historie auszuliefern. Das ist das bessere Scheitern,
aber es bleibt ein Scheitern: entscheide vor der Migration, was diese
Streams sein sollen, nicht danach.
Tag-Queries
Abschnitt betitelt „Tag-Queries“MariaDbQuery liest den events_tags-Index genau so wie
PostgresQuery — dieselben Statements, dieselben drei Pläne, nur die
Platzhalter unterscheiden sich. Die Formen stehen unter
Tag-Queries auf der Postgres-Seite.
import { MariaDbJournal, MariaDbJournalOptions, MariaDbQuery } from 'actor-ts/persistence';
const journalOptions = MariaDbJournalOptions.create().withUrl(process.env.MARIADB_URL!);const eventsJournal = new MariaDbJournal(journalOptions);const query = new MariaDbQuery(eventsJournal);Dialekt-Unterschiede ggü. Postgres
Abschnitt betitelt „Dialekt-Unterschiede ggü. Postgres“Das Verhalten ist identisch; das SQL unterscheidet sich:
| Operation | Postgres | MariaDB |
|---|---|---|
| Platzhalter | $1, $2 | ? |
| Tag-Dedup-Insert | ON CONFLICT DO NOTHING | INSERT IGNORE |
| Snapshot-Upsert | ON CONFLICT … DO UPDATE | ON DUPLICATE KEY UPDATE |
keepN-Prune | NOT IN (SELECT … LIMIT) | derived-table-gewrappte Subquery¹ |
| Durable-Create-Konflikt | ON CONFLICT DO NOTHING → rowCount | reines INSERT, ER_DUP_ENTRY (1062) fangen |
| Concurrency-Backstop | SQLSTATE 23505 | ER_DUP_ENTRY / 1062 |
| Contention-Backstop | SQLSTATE 40001 / 40P01 | ER_CHECKREAD (1020), 1213, 1205² |
| Id-/Tag-Vergleich | TEXT — ohnehin byte-exakt | VARCHAR(255) COLLATE utf8mb4_bin³ |
¹ MySQL/MariaDB lehnen LIMIT in einer nackten IN (SELECT …) gegen die
zu löschende Tabelle ab, daher wrappt der Prune die Subquery in eine
Derived Table.
² Ein unterlegener Writer erreicht den Primary Key nicht immer. Unter
echter Contention bricht InnoDB ihn vorher ab — „Record has changed since
last read” (errno 1020) — der Duplicate-Key-Backstop allein hätte dem
Caller also einen undurchsichtigen JournalError gereicht, ohne
Unterscheidungsmöglichkeit zwischen wiederholbarem Race und echtem
Speicherfehler. Diese Abbrüche werden ebenfalls klassifiziert, aber nur
dann als JournalConcurrencyError gemeldet, wenn ein erneutes Lesen zeigt,
dass der Head sich tatsächlich bewegt hat; sonst bleibt der Fehler stehen,
denn ein Lock-Wait-Timeout gegen eine unbeteiligte lange Transaktion ist
ein echter Fehler, und ein Retry würde sich nur drehen. Für Durable-State-
CAS gilt dasselbe.
³ Postgres vergleicht TEXT byte-exakt und braucht daher nichts; MariaDB
würde sonst einen groß-/kleinschreibungsfaltenden Server-Standard erben und
zwei Entitäten in einen Stream verschmelzen. Siehe
Warum persistence_id und tag kollationiert sind.
BIGINT kann der Connector als JS-bigint liefern; das Backend coerct
Sequence/Revision/Timestamp an der Mapping-Grenze zu number.
Fallstricke
Abschnitt betitelt „Fallstricke“Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- PostgreSQL — das Geschwister-Backend, mit dem ausführlicheren Durchgang zu Registrierung + Concurrency.
- Cassandra-Journal — verteilt, für Scale-out.
- Durable State — die State-orientierte Alternative zum Event Sourcing.
