Gérer les bases de données Cloudflare D1 avec DbGate

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

Cloudflare D1 est une base de données SQL sans serveur, hébergée au plus près de vos Cloudflare Workers. Elle repose sur SQLite, ne demande aucun serveur à configurer et ne coûte rien tant que votre application reste modeste. En revanche, elle ne fournit pas d’interface confortable pour consulter les données. Le tableau de bord Cloudflare propose une console élémentaire et Wrangler permet d’exécuter du SQL en ligne de commande, mais aucun des deux n’est un véritable outil de gestion de bases de données.

Ce guide présente les usages adaptés à D1, ses limites et la manière de la connecter à DbGate pour parcourir, interroger, modifier et sauvegarder vos bases D1 comme vos autres bases de données.

Cloudflare D1 est pris en charge dans DbGate Premium depuis la version 7.3.0. La sauvegarde et la restauration des bases D1 ont été ajoutées dans la version 7.3.2.

Qu’est-ce que Cloudflare D1 ?

D1 est le service de base de données géré de Cloudflare, fondé sur SQLite. Chaque base D1 est une base SQLite complète, stockée et répliquée par Cloudflare. Vous la créez en un clic ou avec wrangler d1 create, vous la liez à un Worker et vous l’interrogez avec du SQL ordinaire.

Ce que D1 apporte :

Les fonctionnalités de SQLite – le même dialecte SQL, les mêmes types de données et fonctions, notamment les fonctions JSON et la recherche en texte intégral avec FTS5
Aucune infrastructure à gérer – ni serveurs, ni pools de connexions, ni correctifs, ni planification de capacité
Une facturation à l’usage – vous payez les lignes lues et écrites ainsi que le stockage, avec un niveau gratuit généreux
De nombreuses petites bases – un compte peut contenir des milliers de bases, ce qui rend envisageable une base distincte par client ou par utilisateur
Time Travel – restauration à n’importe quelle minute de la période de conservation (30 jours avec l’offre payante), sans configuration de sauvegardes
La réplication en lecture – des réplicas facultatifs dans d’autres régions réduisent la latence de lecture pour les utilisateurs répartis dans le monde
Une intégration étroite avec Workers – un Worker accède à sa base au moyen d’une liaison, sans identifiants dans le code ni configuration réseau

Vous pouvez accéder à une base D1 de trois façons :

Liaison à un Worker – c’est ainsi que votre application communique avec D1 en production
Interface Wrangler CLI – pour les migrations et les commandes ponctuelles pendant le développement
API REST de Cloudflare – pour administrer D1 depuis l’extérieur de Cloudflare ; c’est la méthode utilisée par DbGate

Limites à connaître

D1 utilise SQLite, mais ce n’est pas un fichier SQLite local. Avant de l’adopter, vérifiez que ses limites conviennent à votre application. Les valeurs ci-dessous étaient en vigueur lors de la rédaction ; consultez la page officielle des limites de D1 pour les chiffres les plus récents.

Taille de la base – une base est limitée à 10 Go avec l’offre payante et à 500 Mo avec l’offre gratuite. D1 est conçue pour multiplier les petites bases, pas pour agrandir indéfiniment une seule base.
Une seule écriture à la fois – chaque base traite les requêtes successivement. Le débit dépend donc de leur rapidité ; une requête longue bloque les suivantes.
Pas de transactions interactives – vous ne pouvez pas lancer une transaction avec BEGIN, effectuer des opérations puis envoyer COMMIT plus tard. D1 exécute plutôt un lot d’instructions de manière atomique : soit toutes réussissent, soit aucune n’est appliquée.
Taille des instructions et des valeurs – une instruction SQL ne peut pas dépasser 100 Ko, et une ligne, chaîne ou valeur BLOB ne peut pas dépasser 2 Mo. Les gros fichiers doivent aller dans R2, pas dans D1.
Durée des requêtes – une requête ne peut pas durer plus de 30 secondes.
Facturation selon les lignes lues – vous payez chaque ligne qu’une requête lit, pas seulement celles qu’elle renvoie. Parcourir entièrement une grande table coûte cher : de bons index sont donc particulièrement importants.
Pas de fonctions SQLite liées aux fichiers – ATTACH DATABASE, le chargement d’extensions et l’écriture dans sqlite_master sont interdits. Les clés étrangères sont toujours vérifiées ; dans un lot, vous pouvez utiliser PRAGMA defer_foreign_keys = on au lieu de PRAGMA foreign_keys = OFF.
Noms réservés – les tables dont le nom commence par _cf_ sont internes à Cloudflare et ne peuvent être ni lues ni modifiées.
Limites de débit de l’API REST – l’API REST partage les limites globales de l’API Cloudflare. Elle est destinée à l’administration et aux outils, pas au trafic de production. Votre application doit utiliser une liaison à un Worker.

Cas d’usage courants

D1 est particulièrement adaptée si votre application tourne déjà sur Cloudflare ou si les données se répartissent naturellement entre de petites bases indépendantes :

Backends pour Workers et Pages – comptes utilisateurs, paramètres, contenus et commandes des applications web exécutées en périphérie du réseau
Une base par client – chaque client d’une application SaaS dispose de sa propre base isolée, ce qui simplifie la séparation, la suppression et l’exportation des données
Stockage de contenus et de configuration – blogs, contenus de CMS, indicateurs de fonctionnalités, redirections et autres données surtout consultées en lecture, idéalement via des réplicas
Prototypes et projets personnels – l’offre gratuite et la simplicité de mise en place permettent de démarrer rapidement, puis de grandir
Analyses et journaux légers – compteurs, événements et journaux d’audit, tant que chaque base respecte la limite de taille
Caches de données à la périphérie – une copie SQLite de certaines données de votre base principale, proche des utilisateurs

D1 convient mal à une seule grande base OLTP avec de nombreuses écritures, aux traitements nécessitant de longues transactions interactives ou au stockage de gros fichiers binaires. PostgreSQL, MySQL ou une autre base traditionnelle, éventuellement accessible par Cloudflare Hyperdrive, répondent mieux à ces besoins.

Connecter DbGate à Cloudflare D1

DbGate accède à D1 par l’API REST de Cloudflare. Une connexion est liée à un compte Cloudflare et affiche toutes les bases D1 auxquelles le jeton API donne accès.

Étape 1 – Trouver l’identifiant du compte

Connectez-vous au tableau de bord Cloudflare.
Ouvrez Storage & Databases | D1 SQL Database, ou la page d’accueil du compte.
Copiez votre Account ID. Il figure dans les détails du compte et dans l’URL du tableau de bord (dash.cloudflare.com/<account-id>/...).

Étape 2 – Créer un jeton API

Allez dans My Profile | API Tokens et cliquez sur Create Token.
Choisissez Create Custom Token.
Sous Permissions, ajoutez Account | D1 | Edit. Si vous souhaitez seulement lire les données, Read suffit.
Sous Account Resources, sélectionnez le compte qui contient vos bases.
Vous pouvez limiter le jeton à votre adresse IP et fixer une date d’expiration.
Créez puis copiez le jeton. Cloudflare ne l’affiche qu’une seule fois.

Utilisez un jeton distinct pour DbGate afin de pouvoir le révoquer sans toucher aux jetons de vos pipelines de déploiement.

Étape 3 – Créer la connexion dans DbGate

Dans DbGate, cliquez sur New connection.
Sélectionnez Cloudflare D1 comme type de connexion.
Renseignez Cloudflare Account ID et Cloudflare API Token.
Laissez Cloudflare API URL vide, sauf si vous devez passer par un point de terminaison personnalisé. L’adresse par défaut est https://api.cloudflare.com/client/v4.
Si votre réseau l’exige, configurez un proxy HTTP dans les paramètres de connexion.
Cochez éventuellement Is read only pour éviter les modifications accidentelles.
Cliquez sur Test, puis sur Save (ou Connect).

Une fois connecté, DbGate affiche toutes les bases D1 du compte accessibles au jeton. Développez une base pour voir ses tables, ses vues et leurs colonnes, index et clés étrangères.

Si la connexion échoue, DbGate essaie d’en préciser la cause : jeton invalide ou expiré, autorisation D1 manquante, mauvais identifiant de compte ou base qui n’existe plus.

Gérer D1 depuis DbGate

En interne, DbGate traite D1 comme SQLite avec un mode de transport différent. Le navigateur de données, la génération SQL et l’analyse du schéma fonctionnent comme pour les fichiers SQLite locaux : la plupart de vos habitudes restent valables.

Parcourir et modifier les données

Ouvrez une table dans le navigateur de données pour filtrer, trier et rechercher ses lignes, suivre les clés étrangères vers les enregistrements associés ou modifier les valeurs directement dans la grille. Les modifications sont écrites dans D1 lorsque vous les enregistrez.

Puisque D1 facture les lignes lues, utilisez des filtres et des colonnes indexées pour explorer les grandes tables, plutôt que de faire défiler toutes les lignes.

Explorer le schéma

DbGate charge la structure complète de la base : tables, colonnes, clés primaires et étrangères, index et vues. Chaque requête vers D1 est une requête HTTPS. DbGate prépare donc l’analyse du schéma et l’envoie sous forme de quelques requêtes groupées au lieu de centaines de requêtes isolées. Pour une base de taille ordinaire, une analyse complète ne nécessite que deux requêtes.

Les tables internes _cf_* de Cloudflare sont masquées dans le schéma : vous ne voyez que vos propres objets.

Exécuter des requêtes SQL

Ouvrez l’éditeur de requêtes sur une base D1 et écrivez du SQL SQLite comme d’habitude, avec la complétion fondée sur le schéma chargé. Si vous exécutez un script contenant plusieurs instructions, DbGate les envoie à D1 en un seul lot. D1 exécute ce lot de manière atomique : le script s’exécute entièrement ou pas du tout.

À retenir :

Les instructions explicites BEGIN, COMMIT, ROLLBACK et SAVEPOINT sont refusées avec un message clair, car l’API D1 ne gère pas les transactions interactives. Les boutons de transaction sont masqués pour les connexions D1.
Pour une connexion marquée Is read only, DbGate n’autorise que SELECT, EXPLAIN et les instructions PRAGMA de lecture du schéma. Le reste est refusé avant tout envoi à Cloudflare. Pour renforcer la protection, utilisez aussi un jeton API avec l’autorisation D1 | Read.
EXPLAIN QUERY PLAN indique si une requête utilise un index ou parcourt toute la table, ce qui influe directement sur votre facture D1.

Exporter et importer des données

Vous pouvez exporter les résultats des requêtes et les tables en CSV, Excel, JSON et dans les autres formats pris en charge par DbGate. Vous pouvez aussi importer des fichiers dans les tables D1. C’est utile pour une correction ponctuelle, un rapport ou le transfert de données entre D1 et vos autres bases connectées dans DbGate.

Sauvegarder une base D1

Time Travel protège des erreurs pendant la période de conservation, mais ne fournit aucun fichier à conserver, archiver ou ouvrir ailleurs. DbGate peut sauvegarder une base D1 dans un simple fichier SQL :

Faites un clic droit sur la base dans l’arborescence des connexions.
Choisissez Create database backup.
Sélectionnez les éléments à inclure : schéma, données, paramètres de la base et rowids, comme pour une sauvegarde SQLite locale.
Lancez la sauvegarde.

Le résultat est un script SQL SQLite ordinaire. Vous pouvez le restaurer dans une autre base D1, l’ouvrir avec l’outil en ligne de commande sqlite3 ou le charger dans un fichier SQLite local pour le développement et le débogage.

Restaurer dans D1

DbGate peut aussi restaurer un dump SQL dans une base D1, qu’il s’agisse d’une sauvegarde créée par DbGate ou d’un dump SQLite provenant d’ailleurs. Faites un clic droit sur la base cible, choisissez Restore database backup, puis sélectionnez le fichier SQL.

Comme D1 ne peut pas accepter le dump tel quel, DbGate l’adapte pendant la restauration :

Le dump est envoyé par lots de 250 instructions au maximum (et de 1 Mo au maximum). Chaque lot constitue une transaction D1 ; un lot en échec ne laisse donc aucune écriture partielle.
Les instructions de transaction du dump sont ignorées, car chaque lot possède sa propre transaction.
Les clés étrangères sont différées jusqu’à la fin de chaque lot avec PRAGMA defer_foreign_keys = on, comme le recommande Cloudflare pour les imports.
Les objets dont le nom réservé commence par _cf_ sont ignorés.
Les instructions que D1 pourrait refuser d’écrire, comme les compteurs AUTOINCREMENT, les statistiques ou user_version, sont exécutées après les données et ne produisent que des avertissements.
Si Stop on first error est activé, la restauration s’arrête au premier lot en échec ; sinon elle continue et signale toutes les erreurs à la fin.

Deux éléments ne peuvent pas être restaurés par l’API SQL de D1 : les lignes dont l’instruction INSERT dépasse la limite de 100 Ko (généralement à cause de grandes valeurs texte ou BLOB), et les tables virtuelles qu’un dump recrée au moyen de PRAGMA writable_schema. DbGate le signale clairement au lieu d’échouer silencieusement.

La sauvegarde et la restauration permettent aussi de déplacer une base SQLite locale vers D1 : sauvegardez le fichier local avec DbGate, puis restaurez le fichier SQL dans une base D1 vide. L’opération fonctionne également dans l’autre sens, par exemple pour copier des données D1 de production dans un fichier SQLite local destiné aux tests.

La restauration est interdite avec une connexion en lecture seule.

Conseils de sécurité

Le jeton API est stocké avec la connexion, comme les autres identifiants DbGate. Ne le partagez jamais et privilégiez les jetons limités aux autorisations D1, à un seul compte et, si possible, à votre adresse IP.
DbGate veille à ce que le jeton n’apparaisse jamais dans les journaux ni dans les messages d’erreur.
Avec DbGate Team Premium, vous pouvez définir une seule fois la connexion D1 sur le serveur et contrôler les utilisateurs et rôles autorisés à l’employer, plutôt que de distribuer le jeton API à chaque membre de l’équipe.

Conclusion

Cloudflare D1 permet facilement de donner à chaque Worker, projet ou client sa propre base SQL. DbGate facilite le travail avec ces bases : un identifiant de compte et un jeton API suffisent pour parcourir le schéma, modifier les données dans une grille, exécuter du SQL, importer, exporter, sauvegarder et restaurer. Le tout dans l’outil que vous utilisez déjà pour PostgreSQL, MySQL, SQL Server, SQLite et bien d’autres bases de données.

Téléchargez DbGate et essayez-le avec vos bases D1.