Michael JohnsonDal 4 novembre 2026, una query a Cloudflare D1 che restituisce un risultato superiore a 50 MB termina con un errore. Per gli sviluppatori è importante capire a cosa si applica questa modifica: alla dimensione del risultato di una singola query, non alla dimensione massima del database. L’importazione e l’esportazione tramite REST API non rientrano in questo limite, quindi è il modo in cui si leggono i dati a determinare se occorre modificare il flusso di lavoro.
Che cosa è limitato esattamente?
Cloudflare ha descritto la modifica in una nota del 30 ottobre: una query il cui risultato supera i 50 MB restituisce l’errore D1 query result exceeded the maximum response size limit of 50 MB. La data di entrata in vigore è il 4 novembre 2026. La documentazione di D1 indica anch’essa un limite alla dimensione dei risultati delle query; il database può comunque contenere fino a 10 GB con il piano a pagamento o 500 MB con quello gratuito.
Si tratta di livelli distinti: lo spazio di archiviazione determina la quantità di dati contenuti nel database, mentre il limite dei risultati stabilisce quanti dati può restituire una singola query. Un database può quindi contenere molti più di 50 MB di dati ed essere comunque letto a porzioni. Allo stesso tempo, anche una query su un database piccolo può superare il limite se seleziona molte righe con numerose colonne o campi testuali e binari di grandi dimensioni.
Nell’annuncio di Cloudflare sul limite, l’azienda afferma che la soglia copre il 99,999º percentile delle query D1. Si tratta di una stima della distribuzione fornita dal provider; per una verifica concreta è più importante misurare le risposte effettive dell’applicazione e individuare le query che restituiscono grandi quantità di dati.
Perché l’esportazione tramite REST API è un caso a sé?
Di norma, una query dell’applicazione riceve il risultato dell’esecuzione SQL e lo passa al codice chiamante. L’importazione e l’esportazione del database tramite REST API sono operazioni diverse: Cloudflare specifica che non sono soggette alla nuova soglia e continuano a funzionare come prima. Un errore su una selezione di grandi dimensioni, quindi, non significa che sia impossibile esportare grandi volumi di dati dal database.
In pratica, questa distinzione aiuta a scegliere il percorso più adatto. Se l’applicazione deve usare tutti i record per visualizzarli, elaborarli o creare un report, suddividete la lettura in porzioni. Se invece l’obiettivo è trasferire o esportare i dati, valutate l’esportazione tramite REST API anziché tentare di ottenere l’intero database con un’unica risposta SQL.
Come ridurre la risposta senza perdere i dati necessari?
Il primo passo è escludere le colonne superflue. Invece di SELECT *, indicate soltanto i campi necessari per l’operazione in corso. Questo riduce il volume della risposta, soprattutto se la tabella contiene descrizioni lunghe, valori JSON o dati BLOB.
Il secondo passo è leggere le righe a porzioni usando LIMIT e OFFSET, come consiglia Cloudflare. Per esempio, un’interfaccia può caricare la pagina successiva man mano che l’utente scorre, mentre un processo batch può elaborare ciascuna porzione separatamente. Aggiungete un ordinamento stabile, per esempio in base a un identificatore univoco: senza di esso, i confini tra le pagine possono cambiare se i dati vengono modificati tra una query e l’altra.
Per le esportazioni di lunga durata, conviene anche salvare un checkpoint dell’ultimo record elaborato. In questo modo, dopo un’interruzione, il processo può riprendere senza rielaborare l’intero insieme di dati. La soluzione specifica dipende dall’applicazione; il principio fondamentale è limitare la dimensione di ogni risposta, anziché affidarsi a una sola query che restituisce l’intero insieme.
Che cosa verificare nell’applicazione
Iniziate dalle query che restituiscono elenchi voluminosi: esportazioni per i report, schermate amministrative, attività in background e percorsi API che restituiscono array di righe. Registrate temporaneamente il volume della risposta serializzata, oppure il numero e la dimensione dei campi selezionati. Verificate poi il volume massimo previsto, non soltanto il piccolo insieme di dati usato normalmente nei test.
Se dopo la modifica l’applicazione riceve un errore, la documentazione di D1 lo riconduce a risultati superiori a 50 MB e consiglia di selezionare le colonne necessarie o suddividere il risultato in pagine. Questo aiuta a distinguere un problema di dimensione della risposta dai limiti di tempo di esecuzione o di memoria, oppure da problemi di disponibilità del database: errori e cause sono diversi.
In sintesi, per il team il quadro è semplice: le normali query brevi probabilmente non richiederanno modifiche, mentre le letture più ampie dovrebbero passare a un’elaborazione a porzioni. Il limite non impedisce di archiviare un database più grande né blocca l’esportazione tramite REST API; richiede invece di progettare le query in modo che ogni singola risposta resti entro i 50 MB.
