Cloudflare D1: il database SQL serverless basato su SQLite

Cloudflare D1 è il database SQL serverless di Cloudflare basato su SQLite, distribuito globalmente e integrato nativamente con Workers e Pages. Lanciato in beta nel 2022 e disponibile in general availability dal 2024, D1 promette di portare la semplicità di SQLite all'edge computing, con replica automatica e accesso a bassa latenza da qualsiasi Worker. È pensato per applicazioni che hanno bisogno di SQL tradizionale senza gestire un database server.

Architettura distribuita

D1 sfrutta SQLite come motore di base, garantendo compatibilità con migliaia di librerie e tool esistenti. La novità è la distribuzione: ogni database D1 ha una primary location ma viene replicato in read-only sui POP edge dove c'è traffico. Le query di lettura sono servite localmente in pochi millisecondi, mentre le scritture vanno verso la primary con propagazione asincrona. Per la maggior parte dei carichi web (read-heavy) questo modello è ottimale.

Procedura passo-passo

1. Installa Wrangler 3+: npm install -g wrangler.
2. Crea un database: wrangler d1 create mio-db.
3. Annota database_id restituito e aggiungilo a wrangler.toml.
4. Crea uno schema in file schema.sql con CREATE TABLE.
5. Applica lo schema: wrangler d1 execute mio-db --file schema.sql.
6. Nel Worker accedi via binding: const {results} = await env.DB.prepare("SELECT * FROM users").all();.
7. Per query con parametri usa bind: .bind(userId) per prevenire SQL injection.
8. Usa transazioni con env.DB.batch([...]) per atomicità.
9. Esegui migrazioni con wrangler d1 migrations apply.
10. Backup automatico abilitato di default, ripristino dal dashboard.

Casi d'uso ideali

D1 brilla per: blog e CMS dove le letture dominano, autenticazione e sessioni con tabelle utenti compatte, analytics light con aggregazioni periodiche, e-commerce piccolo con catalogo e ordini, landing page con form che salvano lead. È meno indicato per workload molto scrittura-intensivi, transazioni distribuite complesse, dataset multi-TB.

Limiti attuali

D1 ha alcuni limiti pratici: dimensione massima database 10GB, query con max 100k righe per risultato, durata massima query 30 secondi, scritture sequenziali sulla primary (no multi-master). Le funzioni SQLite estese (FTS5, JSON1, R*Tree) sono supportate. Niente stored procedures né trigger complessi. Per progetti enterprise con esigenze più alte conviene valutare Postgres su Hyperdrive o database esterni.

Errori comuni e come risolverli

• D1_ERROR: no such table: hai applicato lo schema sul DB locale ma non remoto. Usa --remote in execute.
• D1_TYPE_ERROR: stai bindando un tipo non supportato (Date, BigInt). Convertili in string o number.
• SQL injection vulnerability: stai concatenando stringhe. Usa prepare + bind sempre.
• Latenza alta da location distante: la primary è in US. Considera che le scritture viaggiano. Le letture sono già replicate.
• Database non raggiungibile: verifica il binding in wrangler.toml e il riavvio del worker.

Confronto con alternative

D1 è gratis fino a 5GB e 5 milioni di righe lette/giorno. PlanetScale (Postgres-compat) ha tier free generoso ma latenze più alte. Supabase offre Postgres completo. Turso è simile a D1 e offre globalmente distribuito SQLite. Per progetti che girano già su Workers/Pages D1 è la scelta integrata con minor friction. Per stack misto valuta soluzioni dedicate.

Pricing

Il piano Free di D1 include 5GB storage, 5 milioni di righe lette/giorno e 100k righe scritte/giorno. Sul piano Workers Paid (5 dollari/mese) sale a 50GB storage, 25 milioni di righe lette/giorno e 50 milioni di righe scritte/mese. Il costo marginale è 0.001 dollari per 1k righe scritte e 0.001 per 1M righe lette: realmente economico per la stragrande maggioranza dei carichi.

Domande frequenti

D: Posso connetterti a D1 via tool come DBeaver?
R: No direttamente, D1 espone solo HTTP API. Esiste però un proxy locale via Wrangler.

D: D1 supporta backup point-in-time?
R: Sì, fino a 30 giorni indietro su piano paid.

D: Posso migrare da MySQL?
R: Sì se le query sono SQL standard. Adattamenti minori per tipi e funzioni SQLite-specific.

D: D1 è production-ready?
R: Sì dal 2024 è in GA. Molti progetti production sono attivi su D1.

Considerazioni operative finali

Quando applichi una configurazione di questo tipo in produzione è sempre buona norma seguire un'approccio incrementale: parti con un test su staging, monitora gli effetti per qualche giorno, poi estendi gradualmente al traffico live. La rete Cloudflare elabora ogni cambiamento in pochi secondi a livello globale, quindi le modifiche sono effettive quasi immediatamente, ma gli effetti collaterali su utenti reali possono richiedere ore o giorni per emergere. Annota nel runbook interno data, motivo e parametri di ogni modifica significativa. Una documentazione precisa accelera enormemente il troubleshooting futuro e facilita il passaggio di consegne tra membri del team.

Vale anche la pena ricordare che Cloudflare aggiorna frequentemente l'interfaccia del dashboard e le posizioni delle voci di menu. La logica e le funzionalità descritte in questa guida restano valide, ma il percorso esatto per raggiungere ogni opzione può variare leggermente nel tempo. In caso di difficoltà a trovare una specifica voce, utilizza la barra di ricerca interna del dashboard oppure consulta la documentazione ufficiale aggiornata. La community Cloudflare sul forum ufficiale e su Stack Overflow è inoltre molto attiva e offre spesso risposte rapide a problemi specifici di configurazione.

Per progetti complessi che coinvolgono più servizi Cloudflare contemporaneamente (CDN, Workers, WAF, Access, R2) conviene strutturare la configurazione come codice tramite Terraform o Pulumi. Questo permette versioning, code review, rollback atomici e deploy ripetibili tra environment. Per team con esigenze più semplici la gestione manuale via dashboard resta perfettamente valida, soprattutto se accompagnata da una checklist scritta delle impostazioni applicate. La scelta dell'approccio dipende dalle dimensioni del progetto e dal grado di automazione desiderato. L'importante è essere consistenti e mantenere tracciabilità delle modifiche effettuate.

Hai bisogno di aiuto?

Se vuoi configurare Cloudflare per il tuo sito con il team di G Tech Group, scrivici tramite il modulo di contatto.