Jak spravovat databáze Cloudflare D1 pomocí DbGate

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

Cloudflare D1 je serverless SQL databáze, která běží v těsné blízkosti Cloudflare Workers. Používá SQLite, nevyžaduje konfiguraci serverů a dokud vaše aplikace nevyroste, nic nestojí. Nenabízí však pohodlné prostředí pro prohlížení dat. Dashboard Cloudflare obsahuje základní konzoli a Wrangler umožňuje spouštět SQL z příkazové řádky, ale ani jedno není plnohodnotný databázový nástroj.

V tomto návodu se dozvíte, k čemu se D1 hodí, jaká má omezení a jak ji připojit k DbGate, abyste mohli své databáze D1 procházet, dotazovat se na ně, upravovat je a zálohovat stejně jako jiné databáze.

Podpora Cloudflare D1 je dostupná v DbGate Premium od verze 7.3.0. Zálohování a obnova databází D1 přibyly ve verzi 7.3.2.

Co je Cloudflare D1?

D1 je spravovaná databázová služba Cloudflare postavená na SQLite. Každá databáze D1 je plnohodnotná databáze SQLite, kterou Cloudflare ukládá a replikuje. Vytvoříte ji jedním kliknutím nebo příkazem wrangler d1 create, připojíte k Workeru a dotazujete se na ni běžným SQL.

Co D1 nabízí:

Vlastnosti SQLite – stejný dialekt SQL, datové typy a funkce, které znáte ze SQLite, včetně funkcí pro JSON a fulltextového vyhledávání pomocí FTS5
Bez vlastní infrastruktury – žádné servery, fondy připojení, aktualizace ani plánování kapacity
Platby podle využití – platíte za přečtené a zapsané řádky a za úložiště; k dispozici je štědrý bezplatný tarif
Mnoho malých databází – účet může obsahovat tisíce databází, takže samostatná databáze pro každého zákazníka nebo uživatele je reálnou možností
Time Travel – obnova do libovolné minuty v rámci doby uchování (v placeném tarifu 30 dní) bez nastavování záloh
Replikace pro čtení – volitelné repliky v jiných regionech zkracují odezvu při čtení pro uživatele po celém světě
Úzká integrace s Workers – Worker přistupuje k databázi přes vazbu bez přihlašovacích údajů v kódu a bez nastavování sítě

K databázi D1 se můžete dostat třemi způsoby:

Vazba na Worker – takto s D1 komunikuje aplikace v produkci
Wrangler CLI – pro migrace a jednorázové příkazy při vývoji
Cloudflare REST API – pro správu mimo Cloudflare; tímto způsobem se připojuje DbGate

Omezení, která je dobré znát

D1 vychází ze SQLite, ale není to místní soubor SQLite. Než se pro ni rozhodnete, ověřte, že její limity vyhovují vaší aplikaci. Následující hodnoty platily v době psaní článku; aktuální údaje najdete na oficiální stránce s limity D1.

Velikost databáze – jedna databáze může mít nejvýše 10 GB v placeném tarifu a 500 MB v bezplatném tarifu. D1 je určena pro mnoho menších databází, ne pro jednu obrovskou.
Jeden zápis v daný okamžik – každá databáze zpracovává dotazy postupně. Propustnost proto závisí na rychlosti dotazů; dlouhé dotazy blokují ostatní.
Bez interaktivních transakcí – nelze zahájit transakci příkazem BEGIN, provést několik kroků a později ji potvrdit příkazem COMMIT. D1 místo toho atomicky provádí dávku příkazů: buď uspějí všechny, nebo se neprovede žádný.
Velikost příkazů a hodnot – jeden příkaz SQL může mít nejvýše 100 KB a jeden řádek, řetězec nebo BLOB nejvýše 2 MB. Velké soubory patří do R2, nikoli do D1.
Doba trvání dotazu – jeden dotaz smí běžet nejvýše 30 sekund.
Účtování podle přečtených řádků – platíte za každý řádek, který dotaz přečte, ne pouze za vrácené řádky. Úplné procházení velké tabulky se prodraží, proto jsou dobré indexy obzvlášť důležité.
Bez funkcí SQLite pracujících přímo se souborem – nejsou povoleny ATTACH DATABASE, načítání rozšíření ani zápis do sqlite_master. Cizí klíče se vždy vynucují; místo PRAGMA foreign_keys = OFF můžete v dávce použít PRAGMA defer_foreign_keys = on.
Vyhrazené názvy – tabulky začínající na _cf_ jsou interní tabulky Cloudflare a nelze je číst ani upravovat.
Limity REST API – REST API podléhá globálním limitům API Cloudflare. Je určené pro správu a nástroje, nikoli pro obsluhu produkčního provozu. Vaše aplikace by měla používat vazbu na Worker.

Typické použití

D1 se hodí zejména tehdy, když už aplikace běží na Cloudflare nebo když lze data přirozeně rozdělit do malých nezávislých databází:

Backendy pro Workers a Pages – uživatelské účty, nastavení, obsah a objednávky webových aplikací běžících na edge síti
Databáze pro každého zákazníka – každý zákazník SaaS aplikace dostane vlastní izolovanou databázi, což usnadňuje oddělení, mazání a export dat
Úložiště obsahu a konfigurace – blogy, obsah CMS, příznaky funkcí, přesměrování a další data, která se hlavně čtou, ideálně přes repliky pro čtení
Prototypy a menší projekty – díky bezplatnému tarifu a jednoduchému nastavení můžete rychle začít a později růst
Jednoduchá analytika a logy – počitadla, události a auditní logy, pokud každá databáze zůstane v rámci velikostního limitu
Edge cache jiných dat – kopie vybraných dat z hlavní databáze ve formátu SQLite blízko uživatelů

D1 se nehodí pro jednu velkou databázi OLTP s častými zápisy, pro úlohy vyžadující dlouhé interaktivní transakce ani pro ukládání velkých binárních souborů. V takových případech lépe poslouží PostgreSQL, MySQL nebo jiná tradiční databáze, případně dostupná přes Cloudflare Hyperdrive.

Připojení DbGate ke Cloudflare D1

DbGate se k D1 připojuje přes Cloudflare REST API. Jedno připojení je svázáno s účtem Cloudflare a zobrazuje všechny databáze D1, ke kterým má přístup použitý API token.

Krok 1 – Najděte ID účtu

Přihlaste se do dashboardu Cloudflare.
Otevřete Storage & Databases | D1 SQL Database, případně domovskou stránku účtu.
Zkopírujte Account ID. Najdete ho v podrobnostech účtu i v adrese dashboardu (dash.cloudflare.com/<account-id>/...).

Krok 2 – Vytvořte API token

Otevřete My Profile | API Tokens a klikněte na Create Token.
Zvolte Create Custom Token.
V části Permissions přidejte Account | D1 | Edit. Pokud potřebujete data pouze číst, stačí Read.
V části Account Resources vyberte účet, ve kterém jsou vaše databáze.
Volitelně omezte token na svou IP adresu a nastavte datum vypršení platnosti.
Token vytvořte a zkopírujte. Cloudflare ho zobrazí jen jednou.

Pro DbGate použijte samostatný token, abyste ho mohli zneplatnit nezávisle na tokenech používaných v nasazovacích procesech.

Krok 3 – Vytvořte připojení v DbGate

V DbGate klikněte na New connection.
Jako typ připojení vyberte Cloudflare D1.
Vyplňte Cloudflare Account ID a Cloudflare API Token.
Pole Cloudflare API URL nechte prázdné, pokud nepotřebujete vlastní koncový bod API. Výchozí adresa je https://api.cloudflare.com/client/v4.
Pokud to vaše síť vyžaduje, nastavte u připojení HTTP proxy.
Chcete-li zabránit nechtěným změnám dat, můžete zaškrtnout Is read only.
Klikněte na Test a potom na Save (nebo Connect).

Po připojení DbGate vypíše všechny databáze D1 v účtu, ke kterým má token přístup. Rozbalením databáze zobrazíte tabulky, pohledy a jejich sloupce, indexy a cizí klíče.

Pokud připojení selže, DbGate se pokusí určit příčinu: neplatný nebo prošlý token, chybějící oprávnění k D1, nesprávné ID účtu nebo již neexistující databázi.

Správa D1 v DbGate

DbGate pracuje s D1 jako se SQLite s jiným způsobem přenosu dat. Prohlížeč dat, generování SQL a analýza schématu fungují stejně jako u místních souborů SQLite, takže většinu známých postupů můžete používat beze změny.

Procházení a úprava dat

V prohlížeči dat otevřete libovolnou tabulku. Můžete filtrovat, řadit a vyhledávat řádky, přecházet po cizích klíčích na související záznamy nebo upravovat hodnoty přímo v mřížce. Změny se do D1 zapíšou při uložení.

Protože D1 účtuje přečtené řádky, při procházení velkých tabulek používejte filtry a indexované sloupce místo procházení všech dat.

Prozkoumání schématu

DbGate načítá celou strukturu databáze: tabulky, sloupce, primární a cizí klíče, indexy a pohledy. Každý dotaz na D1 představuje HTTPS požadavek, proto DbGate naplánuje analýzu schématu předem a odešle několik dávkových požadavků místo stovek samostatných dotazů. U běžně velké databáze stačí pro úplnou analýzu dva požadavky.

Interní tabulky Cloudflare s názvy _cf_* jsou ve schématu skryté, takže vidíte jen své objekty.

Spouštění SQL dotazů

Otevřete editor dotazů pro databázi D1 a pište SQL pro SQLite jako obvykle. Editor nabízí doplňování kódu podle načteného schématu. Pokud spustíte skript s několika příkazy, DbGate je odešle do D1 jako jednu dávku. D1 ji provede atomicky: skript se buď dokončí celý, nebo se neprovede vůbec.

Pamatujte na následující:

Explicitní příkazy BEGIN, COMMIT, ROLLBACK a SAVEPOINT jsou odmítnuty s jasnou zprávou, protože API D1 nepodporuje interaktivní transakce. U připojení D1 se tlačítka pro transakce nezobrazují.
Pokud je připojení označeno Is read only, DbGate povolí jen SELECT, EXPLAIN a příkazy PRAGMA pro čtení schématu. Vše ostatní odmítne ještě před odesláním do Cloudflare. Další vrstvu ochrany zajistí API token s oprávněním D1 | Read.
EXPLAIN QUERY PLAN vám ukáže, zda dotaz používá index, nebo prochází celou tabulku. To má přímý vliv na cenu D1.

Export a import dat

Výsledky dotazů i tabulky lze exportovat do CSV, Excelu, JSON a dalších formátů podporovaných DbGate. Data ze souborů můžete také importovat do tabulek D1. Hodí se to pro jednorázové opravy dat, sestavy i přesuny dat mezi D1 a dalšími databázemi připojenými v DbGate.

Zálohování databáze D1

Time Travel vás chrání před chybami v rámci doby uchování, ale neposkytne soubor, který si můžete ponechat, archivovat nebo otevřít jinde. DbGate umí databázi D1 zálohovat do běžného souboru SQL:

V seznamu připojení klikněte pravým tlačítkem na databázi.
Zvolte Create database backup.
Vyberte, co chcete zahrnout: schéma, data, nastavení databáze a hodnoty rowid. Jde o stejné volby jako při zálohování místní databáze SQLite.
Spusťte zálohování.

Výsledkem je běžný SQL skript pro SQLite. Můžete ho obnovit do jiné databáze D1, otevřít nástrojem sqlite3 z příkazové řádky nebo načíst do místního souboru SQLite pro vývoj a ladění.

Obnova do D1

DbGate umí do databáze D1 obnovit také SQL dump: zálohu vytvořenou v DbGate nebo dump SQLite z jiného zdroje. Klikněte pravým tlačítkem na cílovou databázi, zvolte Restore database backup a vyberte soubor SQL.

Protože D1 nedokáže dump zpracovat přímo, DbGate ho při obnově upraví:

Dump odesílá v dávkách nejvýše 250 příkazů (a nejvýše 1 MB). Každá dávka se provede jako jedna transakce D1, takže neúspěšná dávka nezanechá částečně zapsaná data.
Transakční příkazy z dumpu přeskočí, protože každá dávka tvoří vlastní transakci.
Kontrolu cizích klíčů odloží na konec každé dávky pomocí PRAGMA defer_foreign_keys = on, jak Cloudflare doporučuje pro import.
Objekty s vyhrazenými názvy _cf_ přeskočí.
Příkazy, jejichž zápis D1 nemusí povolit, například počitadla AUTOINCREMENT, statistiky nebo user_version, spustí až po datech a případné potíže uvede pouze jako varování.
Je-li zapnuta volba Stop on first error, obnova se zastaví při první neúspěšné dávce. Jinak pokračuje a na konci vypíše všechny chyby.

Přes SQL API D1 nelze obnovit dvě věci: řádky, jejichž příkaz INSERT přesahuje limit D1 100 KB (obvykle kvůli velkým textovým hodnotám nebo BLOBům), a virtuální tabulky, které dump znovu vytváří pomocí PRAGMA writable_schema. DbGate na ně zřetelně upozorní, místo aby tiše selhal.

Zálohování a obnova zároveň poskytují jednoduchý způsob, jak přesunout místní databázi SQLite do D1: v DbGate zazálohujete místní soubor a vzniklý SQL soubor obnovíte do prázdné databáze D1. Funguje to i opačně, například pro zkopírování produkčních dat D1 do místního souboru SQLite pro testování.

Obnova přes připojení označené jen pro čtení není povolena.

Bezpečnostní poznámky

API token se ukládá s připojením stejně jako ostatní přihlašovací údaje v DbGate. Nikomu ho neposílejte a dávejte přednost tokenům omezeným na oprávnění k D1, jediný účet a pokud možno vaši IP adresu.
DbGate zajišťuje, aby se token nikdy neobjevil v logu ani v chybové zprávě.
V DbGate Team Premium můžete připojení k D1 nastavit jednou na serveru a řídit, kteří uživatelé a role ho smějí používat, místo abyste API token předávali každému členovi týmu.

Závěr

Cloudflare D1 usnadňuje přidělit vlastní SQL databázi každému Workeru, projektu nebo zákazníkovi. DbGate zjednodušuje práci s těmito databázemi: stačí ID účtu a API token a získáte procházení schématu, mřížku pro úpravu dat, SQL editor, import a export dat i zálohování a obnovu. To vše ve stejném nástroji, který už používáte pro PostgreSQL, MySQL, SQL Server, SQLite a mnoho dalších databází.

Stáhněte si DbGate a vyzkoušejte ho se svými databázemi D1.