MariaDB

The MariaDB backend is the sibling of the Postgres backend for teams on MariaDB or MySQL. It provides the same three components — MariaDbJournal, MariaDbSnapshotStore, and MariaDbDurableStateStore — against a single database, via the official mariadb connector (which speaks both MariaDB and MySQL).

It’s a separate implementation from Postgres (not a shared dialect layer), so the SQL is idiomatic MariaDB, but the public contract and behaviour are identical.

Install

mariadb is an optional peer dependency:

bun add mariadb

Lazy-imported on first use, like every other adapter.

Setup

import {
  ActorSystem,
  PersistenceExtensionId,
  registerMariaDbPlugins,
} from 'actor-ts';

const system = new ActorSystem({
  name: 'my-app',
  config: `
    actor-ts.persistence.journal.plugin = "actor-ts.persistence.journal.mariadb"
    actor-ts.persistence.snapshot-store.plugin = "actor-ts.persistence.snapshot-store.mariadb"
  `,
});

const ext = system.extension(PersistenceExtensionId);
const { durableStateStore } = registerMariaDbPlugins(ext, {
  journal:           { poolConfig: conn },
  snapshotStore:     { poolConfig: conn, keepN: 3 },
  durableStateStore: { poolConfig: conn },
});

// conn = { host, port: 3306, user, password, database } — or pass a
// shared `pool` (from mariadb.createPool) at the top level to reuse one
// pool across all three, or a connection URL via `url`.

As with Postgres, the journal + snapshot store are selected by the config plugin IDs, and the durable-state store is returned for you to pass into your DurableStateActor settings.

Configuration

interface MariaDbConnection {
  url?:        string;                    // mariadb://user:pass@host:3306/db
  poolConfig?: Record<string, unknown>;   // { host, port, user, password, database, … }
  pool?:       MariaDbPoolLike;           // pre-built / shared pool
}
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;
}

Discrete poolConfig (host/user/password/database) is the most portable way to connect; url and a pre-built pool are also accepted.

Schema

Same shape as Postgres, with MariaDB types — VARCHAR(255) ids, BIGINT sequence/revision/timestamp, LONGTEXT payloads — and indexes declared inline in CREATE TABLE (portable across MariaDB/MySQL versions, unlike CREATE INDEX IF NOT EXISTS):

CREATE TABLE events (
  persistence_id VARCHAR(255) 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: as Postgres, with the types above

Dialect differences vs. Postgres

The behaviour is identical; the SQL differs:

Operation	Postgres	MariaDB
Placeholders	`$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-wrapped subquery¹
Durable create conflict	`ON CONFLICT DO NOTHING` → rowCount	plain `INSERT`, catch `ER_DUP_ENTRY` (1062)
Concurrency backstop	SQLSTATE `23505`	`ER_DUP_ENTRY` / 1062

¹ MySQL/MariaDB reject LIMIT inside a bare IN (SELECT …) against the table being deleted, so the prune wraps the subquery in a derived table.

BIGINT may surface from the connector as a JS bigint; the backend coerces sequence/revision/timestamp to number at the mapping boundary.

Pitfalls

Where to next

PostgreSQL — the sibling backend, with the fuller walkthrough of registration + concurrency.
Cassandra journal — distributed, for scale-out.
Durable state — the state-oriented alternative to event sourcing.