Come gestire i database Cloudflare D1 con DbGate

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

Cloudflare D1 è un database SQL serverless che si trova vicino ai tuoi Cloudflare Workers. Usa SQLite, non richiede server da configurare e non costa nulla finché la tua applicazione rimane piccola. Quello che manca è un ambiente comodo per esaminare i dati. La dashboard di Cloudflare offre una console essenziale e Wrangler permette di eseguire SQL dalla riga di comando, ma nessuno dei due è uno strumento completo per i database.

Questa guida spiega quando conviene usare D1, quali sono i suoi limiti e come collegarlo a DbGate per esplorare, interrogare, modificare e salvare i database D1 come qualsiasi altro database.

Cloudflare D1 è supportato da DbGate Premium dalla versione 7.3.0. Il backup e il ripristino dei database D1 sono stati aggiunti nella versione 7.3.2.

Che cos’è Cloudflare D1?

D1 è il servizio di database gestito di Cloudflare basato su SQLite. Ogni database D1 è un database SQLite completo, archiviato e replicato da Cloudflare. Puoi crearlo con un clic o con wrangler d1 create, associarlo a un Worker e interrogarlo con SQL ordinario.

D1 offre:

Funzionalità di SQLite – lo stesso dialetto SQL, gli stessi tipi di dati e le stesse funzioni di SQLite, comprese le funzioni JSON e la ricerca full-text con FTS5
Nessuna infrastruttura da gestire – niente server, pool di connessioni, aggiornamenti o pianificazione della capacità
Prezzi basati sull’utilizzo – paghi per le righe lette, quelle scritte e lo spazio di archiviazione, con un generoso piano gratuito
Molti database piccoli – un account può contenerne migliaia, rendendo praticabile un database distinto per ogni tenant o utente
Time Travel – ripristino a qualsiasi minuto del periodo di conservazione (30 giorni nel piano a pagamento), senza configurare backup
Replica in lettura – repliche facoltative in altre regioni riducono la latenza di lettura per gli utenti distribuiti nel mondo
Integrazione diretta con Workers – un Worker accede al database tramite un binding, senza credenziali nel codice né configurazione di rete

Puoi accedere a un database D1 in tre modi:

Binding del Worker – il modo in cui l’applicazione comunica con D1 in produzione
CLI di Wrangler – per migrazioni e comandi occasionali durante lo sviluppo
API REST di Cloudflare – per amministrare D1 dall’esterno di Cloudflare; è il metodo usato da DbGate

Limiti da conoscere

D1 si basa su SQLite, ma non è un file SQLite locale. Prima di sceglierlo, verifica che i suoi limiti siano adatti alla tua applicazione. I valori seguenti erano aggiornati al momento della stesura; consulta la pagina ufficiale sui limiti di D1 per i numeri più recenti.

Dimensioni del database – un singolo database può raggiungere al massimo 10 GB nel piano a pagamento e 500 MB nel piano gratuito. D1 è pensato per scalare con molti database piccoli, non con uno solo enorme.
Una scrittura per volta – ogni database elabora le query in sequenza. La capacità dipende quindi dalla loro velocità; le query lunghe bloccano le successive.
Nessuna transazione interattiva – non puoi avviare una transazione con BEGIN, svolgere operazioni e inviare COMMIT in seguito. D1 esegue invece un batch di istruzioni in modo atomico: riescono tutte oppure non ne viene applicata nessuna.
Dimensioni di istruzioni e valori – un’istruzione SQL può essere lunga al massimo 100 KB; una riga, stringa o valore BLOB al massimo 2 MB. I file grandi vanno in R2, non in D1.
Durata delle query – una query può durare al massimo 30 secondi.
Fatturazione per righe lette – paghi ogni riga che una query legge, non solo quelle restituite. Una scansione completa di una tabella grande è costosa, quindi indici ben progettati sono particolarmente importanti.
Nessuna funzionalità SQLite a livello di file – ATTACH DATABASE, il caricamento di estensioni e la scrittura in sqlite_master non sono consentiti. Le chiavi esterne vengono sempre applicate; invece di PRAGMA foreign_keys = OFF, puoi usare PRAGMA defer_foreign_keys = on in un batch.
Nomi riservati – le tabelle che iniziano con _cf_ sono interne a Cloudflare e non possono essere lette o modificate.
Limiti di frequenza dell’API REST – l’API REST condivide i limiti globali dell’API Cloudflare. È destinata all’amministrazione e agli strumenti, non al traffico di produzione. La tua applicazione dovrebbe usare un binding del Worker.

Casi d’uso tipici

D1 è particolarmente utile quando la tua applicazione è già su Cloudflare o quando i dati si suddividono naturalmente in database piccoli e indipendenti:

Backend per Workers e Pages – account utente, impostazioni, contenuti e ordini delle applicazioni web eseguite all’edge
Un database per tenant – ogni cliente di un’applicazione SaaS ha il proprio database isolato, semplificando separazione, eliminazione ed esportazione dei dati
Archivi di contenuti e configurazione – blog, contenuti CMS, flag di funzionalità, reindirizzamenti e altri dati letti di frequente, idealmente tramite repliche in lettura
Prototipi e progetti personali – il piano gratuito e la configurazione minima permettono di iniziare rapidamente e crescere in seguito
Analisi e log leggeri – contatori, eventi e registri di controllo, purché ogni database rimanga entro il limite di dimensione
Cache di altri dati all’edge – una copia SQLite di dati selezionati dal database principale, vicina agli utenti

D1 non è indicato per un unico grande database OLTP con molte scritture, per carichi che richiedono lunghe transazioni interattive o per grandi file binari. In questi casi sono più adatti PostgreSQL, MySQL o un altro database tradizionale, eventualmente raggiungibile tramite Cloudflare Hyperdrive.

Collegare DbGate a Cloudflare D1

DbGate si collega a D1 tramite l’API REST di Cloudflare. Ogni connessione è associata a un account Cloudflare e mostra tutti i database D1 a cui il token API può accedere.

Passaggio 1 – Trova l’ID account

Accedi alla dashboard di Cloudflare.
Apri Storage & Databases | D1 SQL Database oppure la pagina iniziale dell’account.
Copia il tuo Account ID. Compare nei dettagli dell’account e nell’URL della dashboard (dash.cloudflare.com/<account-id>/...).

Passaggio 2 – Crea un token API

Vai a My Profile | API Tokens e fai clic su Create Token.
Scegli Create Custom Token.
In Permissions, aggiungi Account | D1 | Edit. Se devi soltanto leggere i dati, basta Read.
In Account Resources, seleziona l’account che contiene i database.
Facoltativamente, limita il token al tuo indirizzo IP e imposta una data di scadenza.
Crea e copia il token. Cloudflare lo mostra una sola volta.

Usa un token dedicato a DbGate, così potrai revocarlo senza influire sui token delle pipeline di distribuzione.

Passaggio 3 – Crea la connessione in DbGate

In DbGate, fai clic su New connection.
Seleziona Cloudflare D1 come tipo di connessione.
Compila Cloudflare Account ID e Cloudflare API Token.
Lascia vuoto Cloudflare API URL, a meno che tu non debba raggiungere l’API tramite un endpoint personalizzato. L’indirizzo predefinito è https://api.cloudflare.com/client/v4.
Se la rete lo richiede, configura un proxy HTTP nelle impostazioni della connessione.
Puoi selezionare Is read only per evitare modifiche accidentali.
Fai clic su Test e poi su Save (o Connect).

Dopo la connessione, DbGate elenca tutti i database D1 dell’account accessibili al token. Espandi un database per vedere tabelle, viste e relative colonne, indici e chiavi esterne.

Se la connessione non riesce, DbGate prova a indicarne la causa: token non valido o scaduto, autorizzazione D1 mancante, ID account errato o database non più esistente.

Gestire D1 da DbGate

Internamente, DbGate tratta D1 come SQLite con un diverso mezzo di trasporto. Il browser dei dati, la generazione SQL e l’analisi dello schema sono gli stessi usati per i file SQLite locali, quindi gran parte delle operazioni che conosci funziona allo stesso modo.

Esplorare e modificare i dati

Apri una tabella nel browser dei dati per filtrare, ordinare e cercare le righe, seguire le chiavi esterne verso i record correlati o modificare i valori direttamente nella griglia. Le modifiche vengono scritte in D1 quando le salvi.

Poiché D1 addebita le righe lette, usa filtri e colonne indicizzate quando esplori tabelle grandi invece di scorrere tutti i dati.

Esplorare lo schema

DbGate carica l’intera struttura del database: tabelle, colonne, chiavi primarie ed esterne, indici e viste. Ogni query a D1 comporta una richiesta HTTPS, quindi DbGate pianifica l’analisi dello schema e la invia in poche richieste batch invece che in centinaia di query singole. Per un database di dimensioni normali bastano due richieste per l’analisi completa.

Le tabelle interne _cf_* di Cloudflare sono nascoste nello schema, così vedi solo i tuoi oggetti.

Eseguire query SQL

Apri l’editor di query su un database D1 e scrivi SQL SQLite come al solito, con il completamento del codice basato sullo schema caricato. Se esegui uno script con più istruzioni, DbGate le invia tutte a D1 in un unico batch. D1 lo esegue atomicamente: lo script viene completato per intero oppure non viene applicato nulla.

Tieni presente:

Le istruzioni esplicite BEGIN, COMMIT, ROLLBACK e SAVEPOINT vengono rifiutate con un messaggio chiaro, perché l’API D1 non supporta le transazioni interattive. I pulsanti delle transazioni sono nascosti per le connessioni D1.
Su una connessione contrassegnata Is read only, DbGate consente solo SELECT, EXPLAIN e le istruzioni PRAGMA che leggono lo schema. Tutto il resto viene rifiutato prima dell’invio a Cloudflare. Per maggiore sicurezza, usa anche un token API con autorizzazione D1 | Read.
EXPLAIN QUERY PLAN mostra se una query usa un indice o esamina l’intera tabella, con un effetto diretto sul costo di D1.

Esportare e importare dati

Puoi esportare risultati delle query e tabelle in CSV, Excel, JSON e negli altri formati supportati da DbGate, nonché importare dati da file nelle tabelle D1. È utile per correzioni occasionali, report o trasferimenti tra D1 e altri database collegati in DbGate.

Eseguire il backup di un database D1

Time Travel ti protegge dagli errori durante il periodo di conservazione, ma non produce un file da conservare, archiviare o aprire altrove. DbGate può salvare un database D1 in un normale file SQL:

Fai clic con il pulsante destro sul database nell’albero delle connessioni.
Scegli Create database backup.
Seleziona cosa includere: schema, dati, impostazioni del database e rowid, le stesse opzioni del backup di un database SQLite locale.
Avvia il backup.

Il risultato è un normale script SQL SQLite. Puoi ripristinarlo in un altro database D1, aprirlo con lo strumento da riga di comando sqlite3 o caricarlo in un file SQLite locale per sviluppo e debug.

Ripristinare in D1

DbGate può anche ripristinare un dump SQL in un database D1, sia esso un backup creato da DbGate o un dump SQLite di altra origine. Fai clic con il pulsante destro sul database di destinazione, scegli Restore database backup e seleziona il file SQL.

Poiché D1 non accetta un dump senza modifiche, DbGate lo adatta durante il ripristino:

Il dump viene inviato in batch di massimo 250 istruzioni (e massimo 1 MB). Ogni batch viene eseguito come una transazione D1, quindi un batch fallito non lascia scritture parziali.
Le istruzioni di transazione presenti nel dump vengono saltate, perché ogni batch costituisce una transazione separata.
La verifica delle chiavi esterne viene rinviata alla fine di ogni batch tramite PRAGMA defer_foreign_keys = on, come Cloudflare consiglia per le importazioni.
Gli oggetti con nomi riservati _cf_ vengono saltati.
Le istruzioni che D1 potrebbe rifiutare di scrivere, come contatori AUTOINCREMENT, statistiche o user_version, vengono eseguite dopo i dati e gli eventuali problemi sono segnalati solo come avvisi.
Se Stop on first error è attivo, il ripristino si ferma al primo batch fallito; altrimenti prosegue e segnala tutti gli errori alla fine.

Due elementi non possono essere ripristinati tramite l’API SQL di D1: righe la cui istruzione INSERT supera il limite di 100 KB di D1 (in genere per grandi valori di testo o BLOB) e tabelle virtuali che un dump ricrea con PRAGMA writable_schema. DbGate li segnala chiaramente invece di fallire senza spiegazioni.

Backup e ripristino permettono anche di spostare un database SQLite locale in D1: esegui il backup del file locale con DbGate e ripristina il file SQL in un database D1 vuoto. Funziona anche al contrario, per esempio per copiare dati D1 di produzione in un file SQLite locale da usare nei test.

Non è consentito ripristinare tramite una connessione di sola lettura.

Note sulla sicurezza

Il token API viene salvato insieme alla connessione, come le altre credenziali di DbGate. Non condividerlo e preferisci token limitati alle autorizzazioni D1, a un solo account e, se possibile, al tuo indirizzo IP.
DbGate fa in modo che il token non compaia mai nei log o nei messaggi di errore.
In DbGate Team Premium puoi configurare la connessione D1 una sola volta sul server e controllare quali utenti e ruoli possono usarla, senza distribuire il token API a ogni membro del team.

Conclusione

Cloudflare D1 permette di assegnare facilmente un database SQL a ogni Worker, progetto o tenant. DbGate rende semplice lavorare con questi database: con un ID account e un token API hai esplorazione dello schema, una griglia dati modificabile, un editor SQL, importazione ed esportazione, backup e ripristino. Tutto nello stesso strumento che usi già per PostgreSQL, MySQL, SQL Server, SQLite e molti altri database.

Scarica DbGate e provalo con i tuoi database D1.