Zum Inhalt springen
Deutsch

Cloudflare D1

Das D1-Backend liefert alle drei Persistence-Komponenten gegen eine Cloudflare-D1-Datenbank:

  • D1Journal — das Event-Journal für PersistentActors.
  • D1SnapshotStore — Snapshots, um die Recovery zu begrenzen.
  • D1DurableStateStore — Key-Value-Durable-State für DurableStateActors.

Zwei Dinge sind daran ungewöhnlich:

  • Es braucht kein Paket. D1 hat kein Node-SDK — außerhalb eines Workers ist es eine REST-API — das Backend spricht diese API also mit dem HTTP-Client des Frameworks. Es ist das einzige Backend, das deinem Dependency-Baum nichts hinzufügt.
  • Seine Verifikation endet bei einem Fake. D1 hat keinen Emulator, der sich in einen Container heben lässt; anders als bei jedem anderen Backend gibt es daher keine Live-Integrations-Suite. Siehe Was verifiziert ist und was nicht — das steht bewusst vorne, weil es beeinflussen sollte, wie du es einsetzt.

Das SQL ist mit dem SQLite- und dem libSQL-Backend geteilt, das Schema ist über alle drei identisch, und eine Datenbank kann ohne Migration zwischen ihnen wandern.

Nichts zu installieren:

Terminal-Fenster
bun add actor-ts

Du brauchst eine D1-Datenbank und ein API-Token mit der D1:Edit-Berechtigung, dazu deine Account-ID und die UUID der Datenbank (nicht ihren Namen) — alle drei findest du im Cloudflare-Dashboard oder über wrangler d1 info <name>.

import {
ActorSystem,
ActorSystemOptions,
} from 'actor-ts';
import {
D1DurableStateStoreOptions,
D1JournalOptions,
D1SnapshotStoreOptions,
RegisterD1PluginsOptions,
registerD1Plugins,
} from 'actor-ts/persistence';
const d1SnapshotStoreOptions = D1SnapshotStoreOptions.create()
.withKeepN(3);
const registerOptions = RegisterD1PluginsOptions.create()
.withAccountId(process.env.CLOUDFLARE_ACCOUNT_ID!)
.withDatabaseId(process.env.D1_DATABASE_ID!)
.withApiToken(process.env.CLOUDFLARE_API_TOKEN!)
.withJournal(D1JournalOptions.create() /* .withEventsTable(...) */)
.withSnapshotStore(d1SnapshotStoreOptions)
.withDurableStateStore(D1DurableStateStoreOptions.create() /* .withTable(...) */);
const systemOptions = ActorSystemOptions.create()
// Select the D1 plugins for all three stores.
.withConfig({
'actor-ts': {
persistence: {
journal: { plugin: 'actor-ts.persistence.journal.cloudflare-d1' },
'snapshot-store': { plugin: 'actor-ts.persistence.snapshot-store.cloudflare-d1' },
'durable-state': { plugin: 'actor-ts.persistence.durable-state.cloudflare-d1' },
},
},
})
.withPersistence({ plugins: [(persistence) => registerD1Plugins(persistence, registerOptions)] });
const system = ActorSystem.create('my-app', systemOptions);

Das API-Token geht als Bearer-Token raus — behandle es wie jedes andere Secret und lies es aus der Umgebung, statt es zu committen. Nur einen Teil der drei Credentials zu setzen wird abgelehnt, sobald der Store gebaut wird, denn das ist fast immer eine vergessene Umgebungsvariable. Ein Store wird gebaut, wenn er aufgelöst wird, und nicht in dem Moment, in dem registerD1Plugins zurückkehrt, damit die zusammengeführten Settings, die ein Validator sieht, den HOCON-Block unten einschließen — und das Plug-in läuft innerhalb von ActorSystem.create, wo das System die Stores auflöst, die seine Konfiguration auswählt, und sie dann beim Start öffnet, also lässt ein abgelehnter Satz Credentials den Start scheitern; siehe Stores beim Start öffnen.

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, registerD1Plugins(persistence) braucht damit gar keine Optionen mehr:

import { ActorSystem, ActorSystemOptions } from 'actor-ts';
import { registerD1Plugins } from 'actor-ts/persistence';
const systemOptions = ActorSystemOptions.create().withPersistence({
plugins: [(persistence) => registerD1Plugins(persistence)],
});
const system = ActorSystem.create('my-app', systemOptions);
actor-ts.persistence {
journal { plugin = "actor-ts.persistence.journal.cloudflare-d1" }
snapshot-store { plugin = "actor-ts.persistence.snapshot-store.cloudflare-d1" }
durable-state { plugin = "actor-ts.persistence.durable-state.cloudflare-d1" }
journal.cloudflare-d1 {
account-id = ${?CLOUDFLARE_ACCOUNT_ID}
database-id = ${?D1_DATABASE_ID}
api-token = ${?CLOUDFLARE_API_TOKEN}
}
snapshot-store.cloudflare-d1 {
account-id = ${?CLOUDFLARE_ACCOUNT_ID}
database-id = ${?D1_DATABASE_ID}
api-token = ${?CLOUDFLARE_API_TOKEN}
keep-n = 5
}
durable-state.cloudflare-d1 {
account-id = ${?CLOUDFLARE_ACCOUNT_ID}
database-id = ${?D1_DATABASE_ID}
api-token = ${?CLOUDFLARE_API_TOKEN}
}
}

An registerD1Plugins ü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 Tabellennamen 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. 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.

Auch die beiden Grenzen des Transports haben Blätter (#1490), mit ihren Einheiten unter allen drei Blöcken ausgeliefert: timeout = 30s ist die Frist für einen Request und max-response-bytes = 64M die Obergrenze für einen Response-Body. Beide begrenzen ein ganzes Replay — der Hinweis unten sagt, warum —, eine Historie, die über eine davon hinausgewachsen ist, wird also in der application.conf behoben statt im Code. Ein injizierter client umgeht den Transport und damit beide Werte.

durable-state.plugin wählt jetzt den Durable-State-Store dieses Backends aus. Früher wurde er eifrig gebaut und von registerD1Plugins 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.

  • Deine Daten müssen in D1 liegen. Ein Workers-nahes Deployment, in dem D1 ohnehin das System of Record ist.
  • Du willst null Dependencies. Kein Treiber, kein nativer Build, nichts zu auditieren.

Für alles andere ist libSQL / Turso die bessere Wahl: gleiches Schema, gleiche SQLite-Semantik, ein echter Client, interaktive Transaktionen und eine Live-Suite dahinter.

type D1Connection = {
accountId?: string; // Cloudflare-Account-ID
databaseId?: string; // die UUID der Datenbank, nicht ihr Name
apiToken?: string; // Token mit D1:Edit
baseUrl?: string; // Override für einen Proxy; Default api.cloudflare.com
timeoutMs?: number; // Timeout pro Request, Default 30_000
maxResponseBytes?: number; // Obergrenze für den Response-Body, Default 64 MiB
client?: D1ClientLike; // vorgebauter / geteilter Transport
};
interface D1JournalOptions extends D1Connection {
eventsTable?: string; // Default 'events'
tagsTable?: string; // Default '<eventsTable>_tags'
autoCreateTables?: boolean; // Default true
}
interface D1SnapshotStoreOptions extends D1Connection {
snapshotsTable?: string; // Default 'snapshots'
keepN?: number; // neueste N pro pid; Default 3, <=0 behält alle
autoCreateTables?: boolean;
}
interface D1DurableStateStoreOptions extends D1Connection {
table?: string; // Default 'durable_state'
autoCreateTables?: boolean;
}

Identisch mit dem des SQLite-Backends — events, events_tags, events_meta, snapshots und durable_state, mit CREATE TABLE IF NOT EXISTS angelegt, wenn der Store öffnet — beim Start, oder bei der ersten Verwendung, wenn das Öffnen beim Start abgeschaltet ist.

  • Die Optimistic Concurrency des Journals beruht auf dem Primary Key. append liest den aktuellen Head und fügt ein; ein konkurrierender Writer verletzt den (persistence_id, sequence_nr)-Primary-Key, und das resultierende UNIQUE constraint failed wird in einen JournalConcurrencyError übersetzt.
  • Durable-State-CAS nutzt INSERT … ON CONFLICT DO NOTHING zum Anlegen und UPDATE … WHERE revision = expected zum Aktualisieren, wobei D1s meta.changes als Anzahl betroffener Zeilen gelesen wird.

Jedes andere Backend im Framework hat eine Live-Integrations-Suite, die den vollen Persistence-Contract in CI gegen einen echten Server fährt. D1 hat das nicht und kann es derzeit nicht: es gibt kein D1-Container-Image, und lokal existiert es nur innerhalb von wrangler/Miniflare — einer Workers-Runtime, nicht einer Datenbank, die man in Compose startet.

Also präzise:

SchichtWie sie verifiziert ist
Das SQLMit SQLite und libSQL geteilt und von deren Suiten gegen echtes SQLite ausgeführt
Die drei Storage-ContractsDie geteilte Contract-Suite, gegen einen In-Process-Fake
REST-Envelope und FehlerbehandlungUnit-Tests gegen ein gestubbtes fetch
End-to-End gegen echtes D1Nicht verifiziert