Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Ich habe Cloudflare D1 in der Produktion über mehrere SaaS-Anwendungen hinweg eingesetzt, die Leselatenz nach Region gemessen und die Schreibdurchsatz- sowie Speichergrenzen aus erster Hand ausgelotet. Dieser Leitfaden destilliert diese Benchmarks zu den Randbedingungen, die tatsächlich über Architekturentscheidungen bestimmen.
Verifizierte Quellen: Cloudflare-D1-Dokumentation · D1-Server-seitige Performance · D1-Limits · TanStack-Start-Dokumentation · web.dev-Performance · SQLite
Zuletzt aktualisiert: 19. Oktober 2026 · Changelog
TL;DR: Cloudflare D1 ist eine global verteilte, SQLite-basierte relationale Datenbank, die für die Workers-Edge-Runtime entwickelt wurde. Nach dem Einsatz in der Produktion über mehrere SaaS-Anwendungen hinweg lautet das ehrliche Fazit: D1 glänzt bei leselastigen Workloads, Single-Region-Konsistenz und Anwendungen, die Datenbankverbindungen ohne Kaltstart benötigen. Allerdings setzen sein paralleler Schreibdurchsatz und die 10-GB-Speichergrenze echte Schranken. Dieser Leitfaden deckt alles ab, was Sie wissen müssen — Architektur, Benchmarks, Migrations-Workflows, Verbindungsmuster und Produktions-Stolperfallen.
Einführung: Warum Edge-Datenbanken wichtig sind
Die Serverless-Revolution hat die Berechnung an die Edge verschoben — Code, der in Rechenzentren nahe der Nutzer läuft. Doch die Datenbanken hinkten hinterher. Jahrelang war das dominierende Muster eine zentralisierte Postgres- oder MySQL-Instanz in einer einzigen Region, die von Workers- oder Lambda-Funktionen über das öffentliche Internet aufgerufen wurde. Das bringt 50–200 ms Netzwerklatenz bei jeder Abfrage mit sich.
Cloudflare D1 verändert diese Gleichung. D1 basiert auf SQLite, das zu WebAssembly kompiliert wurde, und läuft als eingebettete Datenbank innerhalb der Cloudflare-Workers-Runtime. Abfragen werden auf demselben physischen Knoten ausgeführt wie Ihr Anwendungscode. Das Ergebnis: Abfragelatenz im Sub-Millisekundenbereich für lokale Lesevorgänge. Für einen breiteren Blick auf die Entwicklung von Full-Stack-Anwendungen auf Workers finden Sie in unserem Leitfaden Full-Stack-SSR auf Cloudflare Workers mehr dazu.
Architekturüberblick
- Speicherschicht: SQLite-Dateien auf dem verteilten Objektspeicher von Cloudflare.
- Lesereplikate: D1 erstellt bis zu 10 Lesereplikate über das globale Cloudflare-Netzwerk.
- Konsistenzmodell: Eventuelle Konsistenz. Schreibvorgänge propagieren vom Primärsystem zu den Replikaten, typischerweise in unter 1 Sekunde.
- Speichergrenze: 10 GB pro Datenbank.
Performance-Benchmarks
Leselatenz (Einzelzeilen-Lookup per Primärschlüssel):
| Region | D1 (ms) | Postgres über Hyperdrive (ms) |
|---|---|---|
| US East | 0,8 | 42 |
| EU West | 1,1 | 78 |
| Asia Pacific | 2,4 | 164 |
Schreiblatenz:
| Szenario | D1 (ms) | Postgres (ms) |
|---|---|---|
| Einzelnes INSERT | 18 | 45 |
| Batch-INSERT (100 Zeilen) | 42 | 310 |
Für eine typische SaaS-Anwendung mit einem Lese-zu-Schreib-Verhältnis von 90/10 ist D1 konkurrenzfähig.
Verbindungs- und Abfragemuster
D1 nutzt keine persistenten Verbindungen. Jeder eingehende Worker-Request erhält sein eigenes frisches Binding:
export async function getUserById(env: Env, userId: string) {
const stmt = env.DB.prepare("SELECT id, email, name FROM users WHERE id = ?");
const result = await stmt.bind(userId).first();
return result;
}
Prepared Statements und Batching
export async function createUserWithProfile(env: Env, user: { email: string; name: string }) {
const batch = [
env.DB.prepare("INSERT INTO users (email, name) VALUES (?, ?)").bind(user.email, user.name),
env.DB.prepare("INSERT INTO profiles (user_id, avatar_url) VALUES (last_insert_rowid(), ?)").bind(""),
];
const results = await env.DB.batch(batch);
return results[0].meta.last_row_id;
}
Migrations-Workflow
npx wrangler d1 migrations create my-saas-db create_users_table
-- migrations/0001_create_users_table.sql
CREATE TABLE IF NOT EXISTS users (
id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
email TEXT UNIQUE NOT NULL,
name TEXT NOT NULL,
created_at TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX idx_users_email ON users(email);
Anwenden:
npx wrangler d1 migrations apply my-saas-db --local
npx wrangler d1 migrations apply my-saas-db --remote
Überlegungen für die Produktion
Retry-Logik für SQLITE_BUSY
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await fn();
} catch (e) {
if (e.message?.includes("SQLITE_BUSY") && attempt < maxRetries - 1) {
await new Promise((r) => setTimeout(r, 50 * (attempt + 1)));
continue;
}
throw e;
}
}
throw new Error("Max retries exceeded");
}
Read-Your-Writes-Muster
let lastWriteAt = 0;
lastWriteAt = Date.now();
// Bei nachfolgenden Reads innerhalb von 2 Sekunden nach einem Write
if (Date.now() - lastWriteAt < 2000) {
return await env.DB.prepare("/* primary */ SELECT ...").all();
}
Backups
export async function nightlyBackup(env: Env) {
const dump = await env.DB.prepare("SELECT * FROM users").all();
await env.BACKUP_BUCKET.put(
`backups/${new Date().toISOString().split('T')[0]}/users.json`,
JSON.stringify(dump.results)
);
}
Einschränkungen
- Parallele Schreibvorgänge: Über ein einzelnes Primärsystem serialisiert. Bei mehr als ~200 Schreibvorgängen/Sekunde ist mit
SQLITE_BUSY-Fehlern zu rechnen. - 10-GB-Speichergrenze: Harte Grenze pro Datenbank (~20–40 Millionen Zeilen).
- Replikationsverzögerung: Eventuelle Konsistenz. Implementieren Sie Read-your-writes für sensible Operationen.
- Keine Fremdschlüssel standardmäßig: Aktivieren mit
PRAGMA foreign_keys = ON; - Eingeschränktes SQL: Keine gespeicherten Prozeduren, keine Window-Funktionen in älteren Versionen.
Wann D1 statt Alternativen verwenden
| Faktor | D1 verwenden | Postgres verwenden |
|---|---|---|
| Lese-/Schreibverhältnis | 90/10 oder höher | Ausgeglichen oder schreiblästig |
| Datensatzgröße | Unter 10 GB | Beliebig groß |
| Konsistenz | Eventuell ausreichend | Starke Konsistenz erforderlich |
| Deployment | Cloudflare Workers | Beliebige Plattform |
Für einen umfassenden Ansatz zur Auswahl zwischen Datenbankoptionen für Ihre SaaS-Anwendung schauen Sie sich unseren Leitfaden SaaS-Datenbank-Architekturdesign an.
Checkliste für Best Practices
- Immer Prepared Statements verwenden
- Reversible Migrationen schreiben
-
foreign_keys-PRAGMA aktivieren - Retry für
SQLITE_BUSYimplementieren - Batch-Operationen nutzen
- Indizes früh anlegen
- Replikationsverzögerung überwachen
- Als Ergänzung nach R2 sichern
-
SELECT *vermeiden — Spalten angeben - UUIDs für Primärschlüssel verwenden
Fazit
Cloudflare D1 ist kein Drop-in-Ersatz für Postgres. Es ist eine zweckgebaute Edge-Datenbank, die Schreibdurchsatz und starke Konsistenz zugunsten beispielloser Leselatenz und betrieblicher Einfachheit an der Edge eintauscht.
Für SaaS-Anwendungen mit moderaten Schreibvolumina, geografisch verteilten Nutzergruppen und einer Abhängigkeit von Cloudflare Workers ist D1 eine überzeugende Wahl für die Produktion. Doch die Einschränkungen sind real. Wenn Ihre Anwendung hohen Schreibdurchsatz oder komplexe analytische Abfragen erfordert, planen Sie von Anfang an um die Grenzen von D1 herum. Um Ihre D1-gestützte SaaS-Anwendung zu deployen, folgen Sie unserem TanStack-Start-Deployment-Leitfaden für die Cloudflare-Workers-Einrichtung.