Como gerenciar bancos de dados Cloudflare D1 com o DbGate

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

O Cloudflare D1 é um banco de dados SQL serverless que fica próximo dos seus Cloudflare Workers. Ele usa SQLite, não exige configurar servidores e não custa nada até sua aplicação crescer. O que ele não oferece é um lugar confortável para examinar os dados. O painel da Cloudflare tem um console básico, e o Wrangler executa SQL pela linha de comando, mas nenhum dos dois é uma ferramenta completa de banco de dados.

Este guia explica para que o D1 é indicado, quais são seus limites e como conectá-lo ao DbGate para explorar, consultar, editar e fazer backup dos seus bancos D1 como de qualquer outro banco de dados.

O suporte ao Cloudflare D1 está disponível no DbGate Premium desde a versão 7.3.0. Backup e restauração de bancos D1 foram adicionados na versão 7.3.2.

O que é o Cloudflare D1?

O D1 é o banco de dados gerenciado da Cloudflare baseado em SQLite. Cada banco D1 é um banco SQLite completo, armazenado e replicado pela Cloudflare. Você o cria com um clique ou com wrangler d1 create, vincula a um Worker e o consulta com SQL comum.

O que o D1 oferece:

Recursos do SQLite – o mesmo dialeto SQL, tipos de dados e funções conhecidos do SQLite, incluindo funções JSON e pesquisa de texto completo com FTS5
Sem infraestrutura própria – sem servidores, pools de conexões, atualizações ou planejamento de capacidade
Cobrança por uso – você paga pelas linhas lidas e gravadas e pelo armazenamento, com uma faixa gratuita generosa
Muitos bancos pequenos – uma conta pode conter milhares de bancos, tornando viável ter um banco separado por cliente ou usuário
Time Travel – recuperação para qualquer minuto dentro do período de retenção (30 dias no plano pago), sem configurar backups
Replicação de leitura – réplicas opcionais em outras regiões reduzem a latência de leitura para usuários distribuídos pelo mundo
Integração direta com Workers – um Worker acessa seu banco por um binding, sem credenciais no código ou configuração de rede

Há três maneiras de acessar um banco D1:

Binding de Worker – a forma usada pela aplicação para se comunicar com o D1 em produção
CLI do Wrangler – para migrações e comandos ocasionais durante o desenvolvimento
API REST da Cloudflare – para administração fora da Cloudflare; é assim que o DbGate se conecta

Limitações importantes

O D1 usa SQLite, mas não é um arquivo SQLite local. Antes de escolhê-lo, verifique se seus limites atendem à sua aplicação. Os valores abaixo eram atuais quando este texto foi escrito; consulte a página oficial de limites do D1 para obter os números mais recentes.

Tamanho do banco – um banco pode ter até 10 GB no plano pago e 500 MB no gratuito. O D1 foi pensado para escalar com muitos bancos menores, e não com um banco gigantesco.
Um escritor por vez – cada banco processa as consultas em sequência. A vazão depende, portanto, da velocidade delas; consultas longas bloqueiam as demais.
Sem transações interativas – você não pode iniciar uma transação com BEGIN, executar operações e confirmar depois com COMMIT. Em vez disso, o D1 executa um lote de instruções atomicamente: todas têm sucesso ou nenhuma é aplicada.
Tamanho de instruções e valores – uma instrução SQL pode ter no máximo 100 KB; uma linha, string ou BLOB individual, no máximo 2 MB. Arquivos grandes devem ficar no R2, não no D1.
Duração das consultas – uma consulta pode levar no máximo 30 segundos.
Cobrança por linhas lidas – você paga por cada linha que a consulta lê, não apenas pelas que retorna. Uma varredura completa de uma tabela grande custa caro; bons índices são especialmente importantes.
Sem recursos do SQLite ligados a arquivos – ATTACH DATABASE, carregamento de extensões e gravação em sqlite_master não são permitidos. As chaves estrangeiras são sempre aplicadas; em vez de PRAGMA foreign_keys = OFF, você pode usar PRAGMA defer_foreign_keys = on dentro de um lote.
Nomes reservados – tabelas que começam com _cf_ são internas da Cloudflare e não podem ser lidas nem alteradas.
Limites de taxa da API REST – a API REST compartilha os limites globais da API da Cloudflare. Ela se destina à administração e a ferramentas, não ao tráfego de produção. Sua aplicação deve usar um binding de Worker.

Usos comuns

O D1 funciona melhor quando sua aplicação já roda na Cloudflare ou quando os dados se dividem naturalmente em bancos pequenos e independentes:

Backends para Workers e Pages – contas de usuários, configurações, conteúdo e pedidos de aplicações web executadas na borda da rede
Um banco por cliente – cada cliente de uma aplicação SaaS recebe seu próprio banco isolado, facilitando a separação, exclusão e exportação de dados
Armazenamento de conteúdo e configuração – blogs, conteúdo de CMS, sinalizadores de recursos, redirecionamentos e outros dados predominantemente lidos, de preferência por réplicas de leitura
Protótipos e projetos menores – a faixa gratuita e a configuração simples permitem começar rapidamente e crescer depois
Análises e logs leves – contadores, eventos e logs de auditoria, desde que cada banco permaneça dentro do limite de tamanho
Caches de outros dados na borda – uma cópia SQLite de dados selecionados do banco principal, perto dos usuários

O D1 não é indicado para um único banco OLTP grande com muitas gravações, cargas que exigem transações interativas longas ou armazenamento de arquivos binários grandes. Nesses casos, PostgreSQL, MySQL ou outro banco tradicional, talvez acessado pelo Cloudflare Hyperdrive, são opções melhores.

Conectando o DbGate ao Cloudflare D1

O DbGate se conecta ao D1 pela API REST da Cloudflare. Cada conexão é vinculada a uma conta Cloudflare e mostra todos os bancos D1 que o token de API consegue acessar.

Etapa 1 – Encontre o ID da conta

Entre no painel da Cloudflare.
Abra Storage & Databases | D1 SQL Database, ou a página inicial da conta.
Copie seu Account ID. Ele aparece nos detalhes da conta e também na URL do painel (dash.cloudflare.com/<account-id>/...).

Etapa 2 – Crie um token de API

Acesse My Profile | API Tokens e clique em Create Token.
Escolha Create Custom Token.
Em Permissions, adicione Account | D1 | Edit. Se você só precisa ler dados, Read é suficiente.
Em Account Resources, selecione a conta que contém seus bancos.
Se desejar, restrinja o token ao seu endereço IP e defina uma data de expiração.
Crie e copie o token. A Cloudflare o mostra apenas uma vez.

Use um token exclusivo para o DbGate, para poder revogá-lo sem afetar os tokens usados nos seus pipelines de implantação.

Etapa 3 – Crie a conexão no DbGate

No DbGate, clique em New connection.
Selecione Cloudflare D1 como tipo de conexão.
Preencha Cloudflare Account ID e Cloudflare API Token.
Deixe Cloudflare API URL em branco, a menos que precise usar um endpoint personalizado. O padrão é https://api.cloudflare.com/client/v4.
Se sua rede exigir, configure um proxy HTTP nas opções da conexão.
Você pode marcar Is read only para evitar alterações acidentais.
Clique em Test e depois em Save (ou Connect).

Depois da conexão, o DbGate lista todos os bancos D1 da conta aos quais o token tem acesso. Expanda um banco para ver suas tabelas, views e respectivas colunas, índices e chaves estrangeiras.

Se a conexão falhar, o DbGate tenta explicar o motivo: token inválido ou expirado, ausência de permissão para D1, ID de conta incorreto ou banco que não existe mais.

Gerenciando o D1 no DbGate

Internamente, o DbGate trata o D1 como SQLite com um transporte diferente. O navegador de dados, a geração de SQL e a análise de esquema funcionam como nos arquivos SQLite locais; quase tudo que você conhece do SQLite funciona da mesma forma.

Explore e edite dados

Abra qualquer tabela no navegador de dados para filtrar, ordenar e pesquisar linhas, seguir chaves estrangeiras até registros relacionados ou editar valores diretamente na grade. As alterações são gravadas no D1 quando você as salva.

Como o D1 cobra por linhas lidas, use filtros e colunas indexadas ao explorar tabelas grandes, em vez de percorrer todos os dados.

Explore o esquema

O DbGate carrega toda a estrutura do banco: tabelas, colunas, chaves primárias e estrangeiras, índices e views. Cada consulta ao D1 é uma requisição HTTPS, então o DbGate planeja a análise do esquema e a envia em algumas requisições em lote, em vez de centenas de consultas individuais. Para um banco de tamanho normal, uma análise completa leva apenas duas requisições.

As tabelas internas _cf_* da Cloudflare ficam ocultas no esquema, para que você veja apenas seus próprios objetos.

Execute consultas SQL

Abra o editor de consultas de um banco D1 e escreva SQL do SQLite normalmente, com preenchimento automático baseado no esquema carregado. Ao executar um script com várias instruções, o DbGate envia todas ao D1 como um único lote. O D1 executa o lote atomicamente: ou o script é concluído por inteiro, ou nada é aplicado.

Lembre-se:

Instruções explícitas BEGIN, COMMIT, ROLLBACK e SAVEPOINT são rejeitadas com uma mensagem clara, pois a API do D1 não oferece transações interativas. Os botões de transação ficam ocultos nas conexões D1.
Em uma conexão marcada como Is read only, o DbGate permite apenas SELECT, EXPLAIN e instruções PRAGMA de leitura do esquema. Todo o restante é rejeitado antes do envio à Cloudflare. Para reforçar a proteção, use também um token com permissão D1 | Read.
EXPLAIN QUERY PLAN mostra se a consulta usa um índice ou percorre a tabela inteira, o que afeta diretamente sua conta do D1.

Exporte e importe dados

Resultados de consultas e tabelas podem ser exportados para CSV, Excel, JSON e outros formatos aceitos pelo DbGate. Você também pode importar dados de arquivos para tabelas D1. Isso ajuda em correções pontuais, relatórios e transferências de dados entre o D1 e outros bancos conectados ao DbGate.

Faça backup de um banco D1

O Time Travel protege contra erros dentro do período de retenção, mas não fornece um arquivo para guardar, arquivar ou abrir em outro lugar. O DbGate pode fazer backup de um banco D1 em um arquivo SQL comum:

Clique com o botão direito no banco na árvore de conexões.
Escolha Create database backup.
Selecione o que incluir: esquema, dados, configurações do banco e rowids, as mesmas opções de um backup local do SQLite.
Inicie o backup.

O resultado é um script SQL comum do SQLite. Você pode restaurá-lo em outro banco D1, abri-lo com a ferramenta de linha de comando sqlite3 ou carregá-lo em um arquivo SQLite local para desenvolvimento e depuração.

Restaure no D1

O DbGate também pode restaurar um dump SQL em um banco D1, seja um backup criado pelo DbGate ou um dump SQLite de outra origem. Clique com o botão direito no banco de destino, escolha Restore database backup e selecione o arquivo SQL.

Como o D1 não aceita o dump sem alterações, o DbGate o adapta durante a restauração:

O dump é enviado em lotes de até 250 instruções (e no máximo 1 MB). Cada lote é executado como uma transação D1, de modo que uma falha não deixa gravações parciais.
As instruções de transação do dump são ignoradas, porque cada lote tem sua própria transação.
A verificação das chaves estrangeiras é adiada até o fim de cada lote com PRAGMA defer_foreign_keys = on, como a Cloudflare recomenda para importações.
Objetos com nomes reservados _cf_ são ignorados.
Instruções que o D1 talvez se recuse a gravar, como contadores AUTOINCREMENT, estatísticas ou user_version, são executadas depois dos dados e eventuais problemas são apenas avisos.
Com Stop on first error ativado, a restauração para no primeiro lote com falha; caso contrário, continua e apresenta todos os erros no final.

Duas coisas não podem ser restauradas pela API SQL do D1: linhas cuja instrução INSERT ultrapassa o limite de 100 KB do D1 (geralmente por valores de texto ou BLOB grandes) e tabelas virtuais que um dump recria com PRAGMA writable_schema. O DbGate informa esses casos claramente, em vez de falhar sem aviso.

O backup e a restauração também oferecem uma forma simples de mover um banco SQLite local para o D1: faça backup do arquivo local no DbGate e restaure o arquivo SQL em um banco D1 vazio. O caminho inverso também funciona, por exemplo para copiar dados de produção do D1 para um arquivo SQLite local para testes.

Não é permitido restaurar por uma conexão somente leitura.

Observações de segurança

O token de API é armazenado com a conexão, assim como as demais credenciais do DbGate. Nunca o compartilhe e prefira tokens limitados a permissões D1, uma única conta e, se possível, seu endereço IP.
O DbGate garante que o token nunca apareça em logs ou mensagens de erro.
No DbGate Team Premium, você pode definir a conexão D1 uma vez no servidor e controlar quais usuários e funções podem usá-la, em vez de distribuir o token para toda a equipe.

Conclusão

O Cloudflare D1 facilita oferecer um banco SQL próprio para cada Worker, projeto ou cliente. O DbGate simplifica o trabalho com esses bancos: com um ID de conta e um token de API, você pode explorar o esquema, editar dados em uma grade, executar SQL, importar e exportar dados, fazer backup e restaurar. Tudo na mesma ferramenta que já usa para PostgreSQL, MySQL, SQL Server, SQLite e muitos outros bancos.

Baixe o DbGate e experimente com seus bancos D1.