Cloudflare D1 begrenzt die Größe von Abfrageergebnissen: Warum Datenbankexporte anders funktionieren

Eine Abfrage an Cloudflare D1, deren Ergebnis größer als 50 MB ist, schlägt seit dem 4. November 2026 fehl. Für Entwickler ist entscheidend, was genau sich ändert: Es geht um die Größe des Ergebnisses einer einzelnen Abfrage, nicht um die maximale Datenbankgröße. Importe und Exporte über die REST API fallen nicht unter dieses Limit. Ob der Arbeitsablauf angepasst werden muss, hängt daher davon ab, wie die Daten gelesen werden.

Was genau ist begrenzt?

Cloudflare beschrieb die Änderung in einem Beitrag vom 30. Oktober: Eine Abfrage, deren Ergebnis 50 MB überschreitet, gibt den Fehler D1 query result exceeded the maximum response size limit of 50 MB zurück. Das Limit gilt ab dem 4. November 2026. In der D1-Dokumentation wird es ebenfalls als Begrenzung der Größe eines Abfrageergebnisses aufgeführt. Eine Datenbank kann im kostenpflichtigen Tarif bis zu 10 GB und im kostenlosen Tarif bis zu 500 MB speichern.

Das sind unterschiedliche Ebenen: Der Speicher legt fest, wie viele Daten in der Datenbank liegen können; das Ergebnislimit bestimmt, wie viele Daten eine einzelne Abfrage zurückgeben kann. Eine Datenbank kann daher deutlich mehr als 50 MB an Daten enthalten und weiterhin in Teilen ausgelesen werden. Selbst eine kleine Datenbank kann das Limit jedoch überschreiten, wenn eine Abfrage viele breite Zeilen oder große Text- und Binärfelder auswählt.

In der Ankündigung des Limits gibt Cloudflare an, dass der Schwellenwert 99,999 Prozent der D1-Abfragen abdeckt. Das ist eine vom Anbieter genannte Einschätzung zur Verteilung der Abfragen. Für die praktische Überprüfung ist es wichtiger, die konkreten Antworten der Anwendung zu messen und Abfragen zu ermitteln, die große Datenmengen zurückgeben.

Warum ist der Export über die REST API ein Sonderfall?

Eine Anwendungsabfrage erhält normalerweise das SQL-Ergebnis und gibt es an den aufrufenden Code weiter. Datenbankimporte und -exporte über die REST API sind andere Vorgänge: Cloudflare weist ausdrücklich darauf hin, dass sie nicht dem neuen Schwellenwert unterliegen und wie bisher funktionieren. Ein Fehler bei einer großen Abfrage bedeutet also nicht, dass sich eine große Datenmenge nicht aus der Datenbank exportieren lässt.

In der Praxis hilft diese Unterscheidung dabei, den passenden Weg zu wählen. Benötigt die Anwendung alle Datensätze zur Anzeige, Verarbeitung oder Erstellung eines Berichts, sollte sie die Daten in Portionen lesen. Sollen Daten dagegen übertragen oder exportiert werden, empfiehlt es sich, den Export über die REST API zu prüfen, statt die gesamte Datenbank mit einer einzigen SQL-Antwort abzurufen.

Wie lässt sich die Antwort verkleinern, ohne benötigte Daten zu verlieren?

Der erste Schritt besteht darin, unnötige Spalten wegzulassen. Statt SELECT * sollten nur die Felder angegeben werden, die für den aktuellen Vorgang erforderlich sind. Das verringert den Umfang der Antwort, insbesondere wenn die Tabelle lange Beschreibungen, JSON- oder BLOB-Werte enthält.

Als Zweites lassen sich Zeilen mit LIMIT und OFFSET in Teilen auslesen, wie Cloudflare empfiehlt. Beispielsweise kann eine Benutzeroberfläche beim Scrollen die nächste Seite abrufen, während ein Batch-Prozess einzelne Portionen verarbeitet. Fügen Sie eine stabile Sortierung hinzu, etwa nach einer eindeutigen ID: Andernfalls können sich die Seitengrenzen verschieben, wenn sich die Daten zwischen den Abfragen ändern.

Bei lang laufenden Exporten empfiehlt es sich außerdem, einen Kontrollpunkt für den zuletzt verarbeiteten Datensatz zu speichern. So kann ein Vorgang nach einem Ausfall fortgesetzt werden, ohne den gesamten Datenbestand erneut zu verarbeiten. Die konkrete Umsetzung hängt von der Anwendung ab. Entscheidend ist, die Größe jeder Antwort zu begrenzen, statt sich auf eine einzige Abfrage zu verlassen, die den gesamten Datenbestand zurückgibt.

Was Sie in Ihrer Anwendung überprüfen sollten

Beginnen Sie mit Abfragen, die große Listen zurückgeben: Berichtsexporte, Verwaltungsansichten, Hintergrundaufgaben und API-Routen, die Arrays von Zeilen ausgeben. Erfassen Sie vorübergehend den Umfang der serialisierten Antwort oder die Anzahl und Größe der ausgewählten Felder. Prüfen Sie anschließend den maximal zu erwartenden Umfang und nicht nur den üblichen kleinen Testdatenbestand.

Wenn die Anwendung nach der Änderung einen Fehler erhält, führt die D1-Dokumentation diesen auf Ergebnisse von mehr als 50 MB zurück und empfiehlt, nur benötigte Spalten auszuwählen oder das Ergebnis in Seiten aufzuteilen. So lässt sich ein Problem mit der Antwortgröße von Einschränkungen bei Ausführungszeit, Arbeitsspeicher oder Datenbankverfügbarkeit unterscheiden: Diese haben andere Fehler und Ursachen.

Das Fazit für Teams ist einfach: Gewöhnliche kurze Abfragen erfordern wahrscheinlich keine Änderungen; große Lesezugriffe sollten dagegen auf eine Verarbeitung in Portionen umgestellt werden. Das Limit verhindert weder die Speicherung einer größeren Datenbank noch Exporte über die REST API. Es macht lediglich erforderlich, Abfragen so zu gestalten, dass jede einzelne Antwort unter 50 MB bleibt.