Cloudflare D1 introdurrà un limite ai risultati delle query: cosa verificare prima del 4 novembre

Se la tua applicazione recupera grandi risultati da Cloudflare D1 con una sola query, controllala prima del 4 novembre: da quella data, una query che restituisce più di 50 MB genererà un errore. La modifica riguarda le dimensioni del risultato, non quelle del database né il volume delle richieste API; importazione ed esportazione tramite REST API mantengono il comportamento attuale.

Cosa cambia esattamente

Cloudflare ha annunciato il limite il 30 ottobre 2026. La nuova regola entrerà in vigore mercoledì 4 novembre: se il risultato di una query SQL supera i 50 MB, D1 restituirà l’errore D1 query result exceeded the maximum response size limit of 50 MB. L’azienda dichiara che questa soglia copre il 99,999° percentile delle query in D1, quindi la stragrande maggioranza delle query resta al di sotto del limite. Si tratta di una stima di Cloudflare relativa alla propria piattaforma, non di una garanzia per una singola applicazione.

È importante distinguere tra il risultato di una query e il trasferimento dei dati. Il limite riguarda il risultato restituito da una query D1; le operazioni di importazione ed esportazione tramite REST API sono esplicitamente escluse dalla regola. Occorre quindi controllare soprattutto le query dell’applicazione che leggono molte righe o record con molte colonne e poi li recuperano per intero.

Perché un risultato voluminoso può passare inosservato

La dimensione della risposta non dipende soltanto dal numero di righe. Una query con molte colonne può restituire un risultato voluminoso anche con un numero moderato di record, soprattutto se le righe contengono testi lunghi o altri valori di grandi dimensioni. La clausola SELECT * include tutte le colonne, anche quando al chiamante ne servono solo alcune. Inoltre, la crescita della tabella nel tempo può far superare la soglia a una query che prima era sicura.

La conseguenza pratica è che conviene controllare non solo le esportazioni amministrative occasionali, ma anche le operazioni ricorrenti dell’applicazione, come i gestori dei report, le attività in background e i metodi API che raccolgono dati da elaborare in seguito. Sono scenari da verificare, non la certezza che ciascuno di essi sarà interessato.

Come preparare le query

Nell’avviso, Cloudflare consiglia di ridurre i dati restituiti: selezionare le colonne necessarie invece di usare SELECT * e suddividere le query più ampie in pagine con LIMIT e OFFSET. Questo approccio riduce le dimensioni di ogni singola risposta e consente di distribuire l’elaborazione su più query.

1. Individua le query ampie. Esamina le query con SELECT *, senza un limite al numero di righe o con campi di testo voluminosi.
2. Limita le colonne selezionate. Elenca solo quelle effettivamente necessarie alla fase successiva dell’elaborazione.
3. Suddividi la lettura in blocchi. Aggiungi il recupero paginato con LIMIT e OFFSET, come suggerisce Cloudflare, ed elabora i blocchi in sequenza.
4. Verifica il comportamento dopo la suddivisione. Assicurati che l’applicazione combini correttamente i risultati e non presupponga di ricevere l’intera query in un’unica risposta.

Se l’applicazione ha bisogno dell’intero insieme di dati per un’esportazione specifica, verifica se l’operazione di esportazione tramite REST API è adatta allo scopo: Cloudflare precisa che il nuovo limite non si applica a questa operazione. Per la normale logica dell’applicazione, questa eccezione non sostituisce la revisione delle risposte SQL voluminose.

A chi si applica la scadenza

La scadenza riguarda direttamente gli utenti D1 le cui query restituiscono più di 50 MB. È opportuno controllare innanzitutto il codice in cui il risultato viene caricato per intero in memoria, trasferito tra componenti o generato per un report. Se le query restituiscono già solo pagine di dimensioni ridotte e i campi necessari, potrebbe non servire alcuna modifica specifica; la decisione dovrebbe basarsi sulle dimensioni effettive delle risposte delle proprie query.

Controllare tutto prima del 4 novembre aiuta a individuare eventuali dipendenze da un’unica risposta voluminosa prima che il limite entri in vigore. Secondo la stima di Cloudflare, per la maggior parte delle query la soglia è ben oltre i volumi usuali; per i sistemi interessati, il piano più diretto consiste nel ridurre i dati selezionati, leggerli a blocchi oppure usare il percorso previsto per le esportazioni tramite REST API.