Cloudflare-D1-Datenbanken mit DbGate verwalten

Published: 2026-10-19 | Jan Procházka

Cloudflare D1 ist eine serverlose SQL-Datenbank, die direkt bei Ihren Cloudflare Workers liegt. Sie basiert auf SQLite, erfordert keine Serverkonfiguration und kostet zunächst nichts, solange Ihre Anwendung klein bleibt. Was fehlt, ist eine komfortable Oberfläche für Ihre Daten. Das Cloudflare-Dashboard bietet eine einfache Konsole, und mit Wrangler können Sie SQL über die Befehlszeile ausführen. Ein vollwertiges Datenbankwerkzeug ist beides nicht.

Dieser Leitfaden erklärt, wofür sich D1 eignet, wo seine Grenzen liegen und wie Sie es mit DbGate verbinden, um Ihre D1-Datenbanken wie andere Datenbanken zu durchsuchen, abzufragen, zu bearbeiten und zu sichern.

Cloudflare D1 wird in DbGate Premium seit Version 7.3.0 unterstützt. Sicherung und Wiederherstellung von D1-Datenbanken kamen in Version 7.3.2 hinzu.

Was ist Cloudflare D1?

D1 ist Cloudflares verwalteter Datenbankdienst auf Basis von SQLite. Jede D1-Datenbank ist eine vollständige SQLite-Datenbank, die Cloudflare speichert und repliziert. Sie erstellen sie mit einem Klick oder mit wrangler d1 create, binden sie an einen Worker und fragen sie mit gewöhnlichem SQL ab.

D1 bietet:

SQLite-Funktionen – denselben SQL-Dialekt, dieselben Datentypen und Funktionen wie SQLite, einschließlich JSON-Funktionen und Volltextsuche mit FTS5
Keine eigene Infrastruktur – keine Server, Verbindungspools, Updates oder Kapazitätsplanung
Nutzungsabhängige Preise – Sie zahlen für gelesene und geschriebene Zeilen sowie Speicherplatz; ein großzügiges kostenloses Kontingent ist enthalten
Viele kleine Datenbanken – ein Konto kann Tausende Datenbanken enthalten, sodass eine eigene Datenbank pro Mandant oder Benutzer praktikabel ist
Time Travel – Wiederherstellung auf eine beliebige Minute innerhalb des Aufbewahrungszeitraums (30 Tage im kostenpflichtigen Tarif), ohne Backups einrichten zu müssen
Lesereplikation – optionale Replikate in anderen Regionen verkürzen die Lesezeiten für weltweit verteilte Benutzer
Enge Integration mit Workers – ein Worker greift über ein Binding auf die Datenbank zu, ohne Zugangsdaten im Code oder Netzwerkkonfiguration

Auf eine D1-Datenbank können Sie auf drei Wegen zugreifen:

Worker-Binding – so kommuniziert Ihre Anwendung in Produktion mit D1
Wrangler CLI – für Migrationen und gelegentliche Befehle während der Entwicklung
Cloudflare REST API – für die Verwaltung außerhalb von Cloudflare; darüber verbindet sich DbGate

Wichtige Einschränkungen

D1 basiert auf SQLite, ist aber keine lokale SQLite-Datei. Prüfen Sie vor der Entscheidung, ob die Grenzen zu Ihrer Anwendung passen. Die folgenden Werte gelten zum Zeitpunkt der Veröffentlichung; aktuelle Angaben finden Sie auf der offiziellen Seite zu den D1-Limits.

Datenbankgröße – eine Datenbank darf im kostenpflichtigen Tarif höchstens 10 GB und im kostenlosen Tarif 500 MB groß sein. D1 skaliert über viele kleinere Datenbanken statt über eine einzige riesige.
Ein Schreibvorgang zur gleichen Zeit – jede Datenbank verarbeitet Abfragen nacheinander. Der Durchsatz hängt daher von deren Geschwindigkeit ab; lang laufende Abfragen blockieren alle folgenden.
Keine interaktiven Transaktionen – Sie können keine Transaktion mit BEGIN starten, zwischendurch arbeiten und später mit COMMIT abschließen. Stattdessen führt D1 einen Batch von Anweisungen atomar aus: Entweder gelingen alle oder keine wird angewendet.
Größe von Anweisungen und Werten – eine SQL-Anweisung darf höchstens 100 KB lang sein, eine einzelne Zeile, Zeichenfolge oder ein BLOB höchstens 2 MB groß. Große Dateien gehören nach R2, nicht nach D1.
Abfragedauer – eine Abfrage darf höchstens 30 Sekunden laufen.
Abrechnung nach gelesenen Zeilen – Sie zahlen für jede Zeile, die eine Abfrage liest, nicht nur für zurückgegebene Zeilen. Ein vollständiger Scan einer großen Tabelle ist teuer; geeignete Indizes sind deshalb besonders wichtig.
Keine dateibezogenen SQLite-Funktionen – ATTACH DATABASE, das Laden von Erweiterungen und Schreibzugriffe auf sqlite_master sind nicht erlaubt. Fremdschlüssel werden immer erzwungen; statt PRAGMA foreign_keys = OFF können Sie innerhalb eines Batchs PRAGMA defer_foreign_keys = on verwenden.
Reservierte Namen – Tabellen, deren Namen mit _cf_ beginnen, sind Cloudflare-intern und können weder gelesen noch geändert werden.
Ratenlimits der REST API – für die REST API gelten Cloudflares globale API-Limits. Sie ist für Verwaltung und Werkzeuge gedacht, nicht für den produktiven Anwendungsverkehr. Ihre Anwendung sollte ein Worker-Binding nutzen.

Typische Anwendungsfälle

D1 eignet sich besonders, wenn Ihre Anwendung bereits auf Cloudflare läuft oder sich die Daten in kleine, unabhängige Datenbanken aufteilen lassen:

Backends für Workers und Pages – Benutzerkonten, Einstellungen, Inhalte und Bestellungen für Webanwendungen am Edge
Eine Datenbank pro Mandant – jeder Kunde einer SaaS-Anwendung erhält eine eigene isolierte Datenbank; das vereinfacht Trennung, Löschung und Export von Daten
Speicher für Inhalte und Konfiguration – Blogs, CMS-Inhalte, Feature-Flags, Weiterleitungen und andere überwiegend gelesene Daten, idealerweise über Lesereplikate bereitgestellt
Prototypen und Nebenprojekte – dank kostenlosem Kontingent und einfacher Einrichtung können Sie schnell starten und später wachsen
Einfache Analysen und Protokolle – Zähler, Ereignisse und Audit-Logs, solange jede Datenbank innerhalb der Größenbegrenzung bleibt
Edge-Caches anderer Daten – eine SQLite-Kopie ausgewählter Daten aus Ihrer Hauptdatenbank in der Nähe Ihrer Benutzer

Für eine einzige große OLTP-Datenbank mit vielen Schreibzugriffen, für lange interaktive Transaktionen oder große Binärdateien eignet sich D1 weniger. Dafür sind PostgreSQL, MySQL oder eine andere klassische Datenbank besser geeignet, gegebenenfalls über Cloudflare Hyperdrive angebunden.

DbGate mit Cloudflare D1 verbinden

DbGate verbindet sich über die Cloudflare REST API mit D1. Eine Verbindung gehört zu einem Cloudflare-Konto und zeigt alle D1-Datenbanken, auf die das API-Token zugreifen darf.

Schritt 1 – Konto-ID finden

Melden Sie sich im Cloudflare-Dashboard an.
Öffnen Sie Storage & Databases | D1 SQL Database oder die Startseite des Kontos.
Kopieren Sie Ihre Account ID. Sie steht in den Kontodetails und auch in der Dashboard-URL (dash.cloudflare.com/<account-id>/...).

Schritt 2 – API-Token erstellen

Öffnen Sie My Profile | API Tokens und klicken Sie auf Create Token.
Wählen Sie Create Custom Token.
Fügen Sie unter Permissions die Berechtigung Account | D1 | Edit hinzu. Wenn Sie Daten nur lesen möchten, reicht Read.
Wählen Sie unter Account Resources das Konto mit Ihren Datenbanken aus.
Optional können Sie das Token auf Ihre IP-Adresse beschränken und ein Ablaufdatum festlegen.
Erstellen und kopieren Sie das Token. Cloudflare zeigt es nur einmal an.

Verwenden Sie für DbGate ein eigenes Token. So können Sie es unabhängig von den Tokens Ihrer Deployment-Pipelines widerrufen.

Schritt 3 – Verbindung in DbGate erstellen

Klicken Sie in DbGate auf New connection.
Wählen Sie Cloudflare D1 als Verbindungstyp.
Tragen Sie Cloudflare Account ID und Cloudflare API Token ein.
Lassen Sie Cloudflare API URL leer, sofern Sie keinen eigenen API-Endpunkt benötigen. Standardmäßig wird https://api.cloudflare.com/client/v4 verwendet.
Konfigurieren Sie bei Bedarf einen HTTP-Proxy in den Verbindungseinstellungen.
Optional können Sie Is read only aktivieren, um unbeabsichtigte Änderungen zu verhindern.
Klicken Sie auf Test und dann auf Save (oder Connect).

Nach dem Verbinden listet DbGate alle D1-Datenbanken des Kontos auf, die für das Token zugänglich sind. Klappen Sie eine Datenbank auf, um Tabellen, Views sowie deren Spalten, Indizes und Fremdschlüssel zu sehen.

Schlägt die Verbindung fehl, versucht DbGate den Grund zu nennen: ein ungültiges oder abgelaufenes Token, fehlende D1-Berechtigung, eine falsche Konto-ID oder eine Datenbank, die nicht mehr existiert.

D1 in DbGate verwalten

Intern behandelt DbGate D1 wie SQLite mit einem anderen Transportweg. Datenbrowser, SQL-Generierung und Schemaanalyse funktionieren wie bei lokalen SQLite-Dateien. Das meiste, was Sie von SQLite kennen, funktioniert daher genauso.

Daten durchsuchen und bearbeiten

Öffnen Sie eine Tabelle im Datenbrowser, um Zeilen zu filtern, zu sortieren und zu durchsuchen, über Fremdschlüssel zu verknüpften Datensätzen zu wechseln oder Werte direkt im Raster zu bearbeiten. Beim Speichern werden die Änderungen in D1 geschrieben.

Da D1 gelesene Zeilen abrechnet, sollten Sie bei großen Tabellen Filter und indizierte Spalten verwenden, statt alle Zeilen durchzublättern.

Schema erkunden

DbGate lädt die vollständige Datenbankstruktur: Tabellen, Spalten, Primär- und Fremdschlüssel, Indizes und Views. Jede Abfrage an D1 ist eine HTTPS-Anfrage. Deshalb plant DbGate die Schemaanalyse im Voraus und sendet wenige Batch-Anfragen statt Hunderten einzelner Abfragen. Bei einer Datenbank üblicher Größe reichen für die vollständige Analyse zwei Anfragen.

Cloudflares interne Tabellen _cf_* werden im Schema ausgeblendet, sodass Sie nur Ihre eigenen Objekte sehen.

SQL-Abfragen ausführen

Öffnen Sie den Abfrageeditor für eine D1-Datenbank und schreiben Sie wie gewohnt SQLite-SQL. Die Codevervollständigung nutzt das geladene Schema. Führen Sie ein Skript mit mehreren Anweisungen aus, sendet DbGate alle als einen Batch an D1. D1 führt den Batch atomar aus: Das Skript läuft entweder vollständig oder gar nicht.

Beachten Sie:

Explizite Anweisungen BEGIN, COMMIT, ROLLBACK und SAVEPOINT werden mit einer verständlichen Meldung abgelehnt, da die D1-API keine interaktiven Transaktionen bietet. Die Transaktionsschaltflächen sind bei D1-Verbindungen ausgeblendet.
Bei einer als Is read only markierten Verbindung erlaubt DbGate nur SELECT, EXPLAIN und PRAGMA-Anweisungen zum Lesen des Schemas. Alles andere wird vor dem Senden an Cloudflare abgelehnt. Verwenden Sie zusätzlich ein API-Token mit der Berechtigung D1 | Read.
EXPLAIN QUERY PLAN zeigt, ob eine Abfrage einen Index verwendet oder die gesamte Tabelle durchsucht. Das wirkt sich direkt auf Ihre D1-Kosten aus.

Daten exportieren und importieren

Abfrageergebnisse und Tabellen lassen sich als CSV, Excel, JSON und in weitere von DbGate unterstützte Formate exportieren. Außerdem können Sie Daten aus Dateien in D1-Tabellen importieren. Das ist praktisch für einmalige Datenkorrekturen, Berichte oder den Datentransfer zwischen D1 und anderen in DbGate verbundenen Datenbanken.

Eine D1-Datenbank sichern

Time Travel schützt innerhalb des Aufbewahrungszeitraums vor Fehlern, liefert aber keine Datei, die Sie aufbewahren, archivieren oder anderswo öffnen können. DbGate kann eine D1-Datenbank als einfache SQL-Datei sichern:

Klicken Sie im Verbindungsbaum mit der rechten Maustaste auf die Datenbank.
Wählen Sie Create database backup.
Wählen Sie aus, was enthalten sein soll: Schema, Daten, Datenbankeinstellungen und rowids. Es sind dieselben Optionen wie bei einer lokalen SQLite-Sicherung.
Starten Sie die Sicherung.

Das Ergebnis ist ein gewöhnliches SQLite-SQL-Skript. Sie können es in einer anderen D1-Datenbank wiederherstellen, mit dem Befehlszeilenwerkzeug sqlite3 öffnen oder für Entwicklung und Fehlersuche in eine lokale SQLite-Datei laden.

In D1 wiederherstellen

DbGate kann auch einen SQL-Dump in einer D1-Datenbank wiederherstellen: ein mit DbGate erstelltes Backup oder einen SQLite-Dump aus anderer Quelle. Klicken Sie mit der rechten Maustaste auf die Zieldatenbank, wählen Sie Restore database backup und dann die SQL-Datei.

Da D1 einen Dump nicht unverändert annimmt, passt DbGate ihn bei der Wiederherstellung an:

Der Dump wird in Batches mit bis zu 250 Anweisungen (und höchstens 1 MB) gesendet. Jeder Batch läuft als eine D1-Transaktion; ein fehlgeschlagener Batch hinterlässt deshalb keine teilweise geschriebenen Daten.
Transaktionsanweisungen aus dem Dump werden übersprungen, weil jeder Batch eine eigene Transaktion bildet.
Fremdschlüsselprüfungen werden mit PRAGMA defer_foreign_keys = on bis zum Ende jedes Batchs aufgeschoben, wie Cloudflare für Importe empfiehlt.
Objekte mit reservierten Namen _cf_ werden übersprungen.
Anweisungen, deren Schreibzugriff D1 möglicherweise verweigert, etwa AUTOINCREMENT-Zähler, Statistiken oder user_version, werden erst nach den Daten ausgeführt; Probleme erscheinen nur als Warnung.
Ist Stop on first error aktiviert, stoppt die Wiederherstellung beim ersten fehlgeschlagenen Batch. Andernfalls läuft sie weiter und meldet am Ende alle Fehler.

Zwei Dinge lassen sich über die SQL-API von D1 nicht wiederherstellen: Zeilen, deren INSERT-Anweisung das D1-Limit von 100 KB überschreitet (meist wegen großer Text- oder BLOB-Werte), und virtuelle Tabellen, die ein Dump über PRAGMA writable_schema neu erstellt. DbGate weist ausdrücklich darauf hin, statt still zu scheitern.

Mit Sicherung und Wiederherstellung können Sie auch eine lokale SQLite-Datenbank nach D1 verschieben: Sichern Sie die lokale Datei mit DbGate und stellen Sie die SQL-Datei in einer leeren D1-Datenbank wieder her. Umgekehrt funktioniert es ebenfalls, etwa um produktive D1-Daten zum Testen in eine lokale SQLite-Datei zu kopieren.

Über eine schreibgeschützte Verbindung ist keine Wiederherstellung möglich.

Sicherheitshinweise

Das API-Token wird wie andere DbGate-Zugangsdaten zusammen mit der Verbindung gespeichert. Geben Sie es niemals weiter und bevorzugen Sie Tokens, die auf D1-Berechtigungen, ein einzelnes Konto und möglichst Ihre IP-Adresse beschränkt sind.
DbGate sorgt dafür, dass das Token weder in Protokollen noch in Fehlermeldungen erscheint.
Mit DbGate Team Premium können Sie die D1-Verbindung einmal auf dem Server einrichten und steuern, welche Benutzer und Rollen sie verwenden dürfen, statt das API-Token an jedes Teammitglied zu verteilen.

Fazit

Cloudflare D1 macht es leicht, jedem Worker, Projekt oder Mandanten eine eigene SQL-Datenbank zu geben. DbGate erleichtert die Arbeit mit diesen Datenbanken: Mit Konto-ID und API-Token erhalten Sie Schemaübersicht, ein bearbeitbares Datenraster, einen SQL-Editor, Datenimport und -export sowie Sicherung und Wiederherstellung. Alles steht in demselben Werkzeug bereit, das Sie bereits für PostgreSQL, MySQL, SQL Server, SQLite und viele andere Datenbanken nutzen.

Laden Sie DbGate herunter und probieren Sie es mit Ihren D1-Datenbanken aus.