Ako spravovať databázy Cloudflare D1 pomocou DbGate

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

Cloudflare D1 je serverless SQL databáza umiestnená blízko vašich Cloudflare Workers. Používa SQLite, nevyžaduje konfiguráciu serverov a kým vaša aplikácia nevyrastie, nič nestojí. Neposkytuje však pohodlné prostredie na prezeranie dát. Dashboard Cloudflare má základnú konzolu a Wrangler dokáže spúšťať SQL z príkazového riadka, no ani jedno nie je plnohodnotný databázový nástroj.

V tomto návode sa dozviete, na čo sa D1 hodí, aké sú jej obmedzenia a ako ju pripojiť k DbGate, aby ste mohli svoje databázy D1 prehliadať, dopytovať, upravovať a zálohovať podobne ako iné databázy.

Podpora Cloudflare D1 je dostupná v DbGate Premium od verzie 7.3.0. Zálohovanie a obnova databáz D1 pribudli vo verzii 7.3.2.

Čo je Cloudflare D1?

D1 je spravovaná databázová služba Cloudflare postavená na SQLite. Každá databáza D1 je plnohodnotná databáza SQLite, ktorú Cloudflare ukladá a replikuje. Vytvoríte ju jedným kliknutím alebo príkazom wrangler d1 create, pripojíte k Workeru a dopytujete pomocou bežného SQL.

Čo D1 ponúka:

Vlastnosti SQLite – rovnaký dialekt SQL, dátové typy a funkcie ako v SQLite, vrátane funkcií JSON a fulltextového vyhľadávania pomocou FTS5
Bez vlastnej infraštruktúry – žiadne servery, fondy pripojení, aktualizácie ani plánovanie kapacity
Platby podľa využitia – platíte za prečítané a zapísané riadky a úložisko; k dispozícii je veľkorysý bezplatný program
Veľa malých databáz – účet môže obsahovať tisíce databáz, takže samostatná databáza pre každého zákazníka či používateľa je reálnou možnosťou
Time Travel – obnova do ľubovoľnej minúty v rámci obdobia uchovávania (30 dní v platenom programe) bez nastavovania záloh
Replikácia na čítanie – voliteľné repliky v iných regiónoch znižujú latenciu čítania pre používateľov po celom svete
Úzka integrácia s Workers – Worker pristupuje k databáze cez väzbu bez prihlasovacích údajov v kóde a bez nastavovania siete

K databáze D1 sa dostanete tromi spôsobmi:

Väzba na Worker – takto s D1 komunikuje aplikácia v produkcii
Wrangler CLI – na migrácie a jednorazové príkazy počas vývoja
Cloudflare REST API – na správu mimo Cloudflare; týmto spôsobom sa pripája DbGate

Obmedzenia, ktoré treba poznať

D1 vychádza zo SQLite, ale nie je to miestny súbor SQLite. Pred výberom overte, či jej limity vyhovujú vašej aplikácii. Nasledujúce hodnoty platili v čase písania článku; aktuálne čísla nájdete na oficiálnej stránke s limitmi D1.

Veľkosť databázy – jedna databáza môže mať najviac 10 GB v platenom programe a 500 MB v bezplatnom. D1 je určená na mnoho menších databáz, nie na jednu obrovskú.
Jeden zápis v danom okamihu – každá databáza spracúva dopyty postupne. Priepustnosť preto závisí od ich rýchlosti; dlhé dopyty blokujú ostatné.
Bez interaktívnych transakcií – nemožno začať transakciu príkazom BEGIN, urobiť niekoľko krokov a neskôr ju potvrdiť príkazom COMMIT. D1 namiesto toho atomicky vykoná dávku príkazov: buď uspejú všetky, alebo sa nevykoná žiadny.
Veľkosť príkazov a hodnôt – jeden príkaz SQL môže mať najviac 100 KB a jeden riadok, reťazec alebo BLOB najviac 2 MB. Veľké súbory patria do R2, nie do D1.
Trvanie dopytu – jeden dopyt môže bežať najviac 30 sekúnd.
Účtovanie podľa prečítaných riadkov – platíte za každý riadok, ktorý dopyt prečíta, nie iba za vrátené riadky. Úplné prechádzanie veľkej tabuľky je drahé, preto sú dobré indexy mimoriadne dôležité.
Bez súborových funkcií SQLite – ATTACH DATABASE, načítavanie rozšírení ani zápis do sqlite_master nie sú povolené. Cudzie kľúče sa vždy vynucujú; namiesto PRAGMA foreign_keys = OFF môžete v dávke použiť PRAGMA defer_foreign_keys = on.
Vyhradené názvy – tabuľky začínajúce na _cf_ sú interné tabuľky Cloudflare a nemožno ich čítať ani upravovať.
Limity REST API – REST API podlieha globálnym limitom API Cloudflare. Je určené na správu a nástroje, nie na obsluhu produkčnej prevádzky. Vaša aplikácia by mala používať väzbu na Worker.

Typické použitie

D1 sa hodí najmä vtedy, keď vaša aplikácia už beží na Cloudflare alebo keď sa dáta prirodzene rozdeľujú do malých nezávislých databáz:

Backendy pre Workers a Pages – používateľské účty, nastavenia, obsah a objednávky webových aplikácií bežiacich na edge sieti
Databáza pre každého zákazníka – každý zákazník SaaS aplikácie dostane vlastnú izolovanú databázu, čo uľahčuje oddelenie, mazanie a export dát
Úložiská obsahu a konfigurácie – blogy, obsah CMS, príznaky funkcií, presmerovania a ďalšie prevažne čítané dáta, ideálne cez repliky na čítanie
Prototypy a menšie projekty – vďaka bezplatnému programu a jednoduchému nastaveniu môžete rýchlo začať a neskôr rásť
Jednoduchá analytika a logy – počítadlá, udalosti a auditné logy, ak každá databáza zostane v rámci limitu veľkosti
Edge cache iných dát – kópia vybraných dát z hlavnej databázy vo formáte SQLite blízko používateľov

D1 sa nehodí na jednu veľkú databázu OLTP s častými zápismi, na úlohy vyžadujúce dlhé interaktívne transakcie ani na veľké binárne súbory. V takých prípadoch lepšie poslúži PostgreSQL, MySQL alebo iná tradičná databáza, prípadne dostupná cez Cloudflare Hyperdrive.

Pripojenie DbGate ku Cloudflare D1

DbGate sa k D1 pripája cez Cloudflare REST API. Jedno pripojenie je viazané na účet Cloudflare a zobrazuje všetky databázy D1, ku ktorým má použitý API token prístup.

Krok 1 – Nájdite ID účtu

Prihláste sa do dashboardu Cloudflare.
Otvorte Storage & Databases | D1 SQL Database, prípadne domovskú stránku účtu.
Skopírujte Account ID. Nájdete ho v podrobnostiach účtu aj v adrese dashboardu (dash.cloudflare.com/<account-id>/...).

Krok 2 – Vytvorte API token

Otvorte My Profile | API Tokens a kliknite na Create Token.
Vyberte Create Custom Token.
V časti Permissions pridajte Account | D1 | Edit. Ak potrebujete dáta iba čítať, stačí Read.
V časti Account Resources vyberte účet, v ktorom sú vaše databázy.
Voliteľne obmedzte token na svoju IP adresu a nastavte dátum vypršania platnosti.
Token vytvorte a skopírujte. Cloudflare ho zobrazí iba raz.

Pre DbGate použite samostatný token, aby ste ho mohli zneplatniť nezávisle od tokenov používaných pri nasadzovaní.

Krok 3 – Vytvorte pripojenie v DbGate

V DbGate kliknite na New connection.
Ako typ pripojenia vyberte Cloudflare D1.
Vyplňte Cloudflare Account ID a Cloudflare API Token.
Pole Cloudflare API URL nechajte prázdne, ak nepotrebujete vlastný koncový bod API. Predvolená adresa je https://api.cloudflare.com/client/v4.
Ak to vaša sieť vyžaduje, nastavte v pripojení HTTP proxy.
Na ochranu pred nechcenými zmenami môžete zaškrtnúť Is read only.
Kliknite na Test a potom na Save (alebo Connect).

Po pripojení DbGate vypíše všetky databázy D1 v účte, ku ktorým má token prístup. Rozbalením databázy zobrazíte tabuľky, pohľady a ich stĺpce, indexy a cudzie kľúče.

Ak pripojenie zlyhá, DbGate sa pokúsi určiť príčinu: neplatný alebo exspirovaný token, chýbajúce oprávnenie k D1, nesprávne ID účtu alebo databázu, ktorá už neexistuje.

Správa D1 v DbGate

DbGate pracuje s D1 ako so SQLite s iným spôsobom prenosu dát. Prehliadač dát, generovanie SQL a analýza schémy fungujú rovnako ako pri miestnych súboroch SQLite, takže väčšinu známych postupov môžete používať bez zmeny.

Prehliadanie a úprava dát

V prehliadači dát otvorte ľubovoľnú tabuľku. Môžete filtrovať, triediť a vyhľadávať riadky, prechádzať cez cudzie kľúče na súvisiace záznamy alebo upravovať hodnoty priamo v mriežke. Zmeny sa do D1 zapíšu po uložení.

Keďže D1 účtuje prečítané riadky, pri prehliadaní veľkých tabuliek používajte filtre a indexované stĺpce namiesto prechádzania všetkých dát.

Preskúmanie schémy

DbGate načíta celú štruktúru databázy: tabuľky, stĺpce, primárne a cudzie kľúče, indexy a pohľady. Každý dopyt na D1 predstavuje HTTPS požiadavku, preto DbGate naplánuje analýzu schémy vopred a odošle niekoľko dávkových požiadaviek namiesto stoviek samostatných dopytov. Pri bežne veľkej databáze stačia na úplnú analýzu dve požiadavky.

Interné tabuľky Cloudflare s názvami _cf_* sú v schéme skryté, takže vidíte iba svoje objekty.

Spúšťanie SQL dopytov

Otvorte editor dopytov pre databázu D1 a píšte SQL pre SQLite ako zvyčajne. Editor ponúka dopĺňanie kódu podľa načítanej schémy. Ak spustíte skript s viacerými príkazmi, DbGate ich odošle do D1 ako jednu dávku. D1 ju vykoná atomicky: skript sa buď dokončí celý, alebo sa nevykoná vôbec.

Pamätajte na toto:

Explicitné príkazy BEGIN, COMMIT, ROLLBACK a SAVEPOINT sa odmietnu s jasnou správou, pretože API D1 nepodporuje interaktívne transakcie. Pri pripojeniach D1 sa tlačidlá transakcií nezobrazujú.
Ak je pripojenie označené Is read only, DbGate povolí len SELECT, EXPLAIN a príkazy PRAGMA na čítanie schémy. Všetko ostatné odmietne ešte pred odoslaním do Cloudflare. Ďalšiu vrstvu ochrany poskytne API token s oprávnením D1 | Read.
EXPLAIN QUERY PLAN ukáže, či dopyt používa index, alebo prechádza celú tabuľku. To má priamy vplyv na cenu D1.

Export a import dát

Výsledky dopytov aj tabuľky môžete exportovať do CSV, Excelu, JSON a ďalších formátov podporovaných DbGate. Dáta zo súborov môžete tiež importovať do tabuliek D1. Hodí sa to na jednorazové opravy dát, zostavy aj presun dát medzi D1 a ďalšími databázami pripojenými v DbGate.

Zálohovanie databázy D1

Time Travel vás chráni pred chybami v rámci obdobia uchovávania, no neposkytne súbor, ktorý môžete ponechať, archivovať alebo otvoriť inde. DbGate dokáže databázu D1 zálohovať do bežného súboru SQL:

V strome pripojení kliknite pravým tlačidlom na databázu.
Vyberte Create database backup.
Zvoľte, čo zahrnúť: schému, dáta, nastavenia databázy a hodnoty rowid. Sú to rovnaké možnosti ako pri zálohovaní miestnej databázy SQLite.
Spustite zálohovanie.

Výsledkom je bežný SQL skript pre SQLite. Môžete ho obnoviť do inej databázy D1, otvoriť nástrojom sqlite3 z príkazového riadka alebo načítať do miestneho súboru SQLite na vývoj a ladenie.

Obnova do D1

DbGate dokáže do databázy D1 obnoviť aj SQL dump: zálohu vytvorenú v DbGate alebo dump SQLite z iného zdroja. Kliknite pravým tlačidlom na cieľovú databázu, vyberte Restore database backup a zvoľte súbor SQL.

Keďže D1 nedokáže dump prijať priamo, DbGate ho počas obnovy upraví:

Dump posiela v dávkach najviac 250 príkazov (a najviac 1 MB). Každá dávka sa vykoná ako jedna transakcia D1, takže neúspešná dávka nezanechá čiastočne zapísané dáta.
Transakčné príkazy z dumpu preskočí, pretože každá dávka je samostatnou transakciou.
Kontrolu cudzích kľúčov odloží na koniec každej dávky pomocou PRAGMA defer_foreign_keys = on, ako Cloudflare odporúča pri importe.
Objekty s vyhradenými názvami _cf_ preskočí.
Príkazy, ktorých zápis D1 nemusí povoliť, napríklad počítadlá AUTOINCREMENT, štatistiky alebo user_version, spustí až po dátach a prípadné problémy uvedie len ako upozornenia.
Ak je zapnutá voľba Stop on first error, obnova sa zastaví pri prvej neúspešnej dávke. Inak pokračuje a na konci vypíše všetky chyby.

Cez SQL API D1 nemožno obnoviť dve veci: riadky, ktorých príkaz INSERT prekračuje limit D1 100 KB (obyčajne pre veľké textové hodnoty alebo BLOB), a virtuálne tabuľky, ktoré dump opäť vytvára pomocou PRAGMA writable_schema. DbGate na ne jasne upozorní namiesto tichého zlyhania.

Zálohovanie a obnova zároveň predstavujú jednoduchý spôsob, ako presunúť miestnu databázu SQLite do D1: v DbGate zálohujte miestny súbor a vzniknutý SQL súbor obnovte do prázdnej databázy D1. Funguje to aj naopak, napríklad na skopírovanie produkčných dát D1 do miestneho súboru SQLite na testovanie.

Obnova cez pripojenie určené len na čítanie nie je povolená.

Bezpečnostné poznámky

API token sa ukladá s pripojením rovnako ako ostatné prihlasovacie údaje v DbGate. Nikomu ho neposielajte a uprednostnite tokeny obmedzené na oprávnenia k D1, jeden účet a podľa možnosti vašu IP adresu.
DbGate zabezpečuje, aby sa token nikdy neobjavil v logoch ani v chybových správach.
V DbGate Team Premium môžete pripojenie k D1 nastaviť raz na serveri a riadiť, ktorí používatelia a roly ho smú využívať, namiesto poskytovania API tokenu každému členovi tímu.

Záver

Cloudflare D1 uľahčuje prideliť vlastnú SQL databázu každému Workeru, projektu alebo zákazníkovi. DbGate zjednodušuje prácu s týmito databázami: stačí ID účtu a API token a získate prehliadanie schémy, mriežku na úpravu dát, SQL editor, import a export dát aj zálohovanie a obnovu. To všetko v rovnakom nástroji, ktorý používate pre PostgreSQL, MySQL, SQL Server, SQLite a mnoho ďalších databáz.

Stiahnite si DbGate a vyskúšajte ho so svojimi databázami D1.