Cómo gestionar bases de datos Cloudflare D1 con DbGate

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

Cloudflare D1 es una base de datos SQL serverless situada junto a tus Cloudflare Workers. Utiliza SQLite, no requiere configurar servidores y es gratuita hasta que tu aplicación crece. Lo que no ofrece es un lugar cómodo para examinar los datos. El panel de Cloudflare tiene una consola básica y Wrangler permite ejecutar SQL desde la línea de comandos, pero ninguno de los dos es una herramienta de bases de datos completa.

Esta guía explica para qué sirve D1, cuáles son sus límites y cómo conectarla a DbGate para explorar, consultar, editar y respaldar tus bases de datos D1 como cualquier otra base de datos.

Cloudflare D1 está disponible en DbGate Premium desde la versión 7.3.0. La copia de seguridad y la restauración de bases D1 se añadieron en la versión 7.3.2.

¿Qué es Cloudflare D1?

D1 es la base de datos administrada de Cloudflare basada en SQLite. Cada base D1 es una base SQLite completa que Cloudflare almacena y replica. Puedes crearla con un clic o con wrangler d1 create, vincularla a un Worker y consultarla con SQL normal.

Qué ofrece D1:

Funciones de SQLite – el mismo dialecto SQL, tipos de datos y funciones que conoces de SQLite, incluidas las funciones JSON y la búsqueda de texto completo con FTS5
Sin infraestructura propia – sin servidores, pools de conexiones, parches ni planificación de capacidad
Precios según el uso – pagas por filas leídas, filas escritas y almacenamiento, con un generoso nivel gratuito
Muchas bases pequeñas – una cuenta puede contener miles de bases, por lo que es viable tener una base independiente por cliente o usuario
Time Travel – recuperación hasta cualquier minuto del periodo de retención (30 días en el plan de pago), sin configurar copias de seguridad
Replicación de lectura – réplicas opcionales en otras regiones para reducir la latencia de lectura de usuarios de todo el mundo
Integración estrecha con Workers – un Worker accede a su base mediante un binding, sin credenciales en el código ni configuración de red

Hay tres formas de acceder a una base D1:

Binding de Worker – la forma en que tu aplicación habla con D1 en producción
CLI de Wrangler – para migraciones y comandos puntuales durante el desarrollo
API REST de Cloudflare – para administrarla desde fuera de Cloudflare; así se conecta DbGate

Límites que debes conocer

D1 se basa en SQLite, pero no es un archivo SQLite local. Antes de elegirla, comprueba que sus límites se ajusten a tu aplicación. Los valores siguientes eran los vigentes al redactar este artículo; consulta la página oficial de límites de D1 para conocer las cifras actuales.

Tamaño de la base – cada base está limitada a 10 GB en el plan de pago y 500 MB en el gratuito. D1 está pensada para escalar con muchas bases pequeñas, no con una sola base enorme.
Un escritor a la vez – cada base procesa las consultas una tras otra. El rendimiento depende de lo rápidas que sean; las consultas largas bloquean las demás.
Sin transacciones interactivas – no puedes iniciar una transacción con BEGIN, realizar operaciones y confirmarla más tarde con COMMIT. En su lugar, D1 ejecuta un lote de sentencias de forma atómica: o se aplican todas o no se aplica ninguna.
Tamaño de sentencias y valores – una sentencia SQL puede ocupar como máximo 100 KB, y una fila, cadena o BLOB individual, 2 MB. Los archivos grandes deben ir a R2, no a D1.
Duración de las consultas – una consulta puede ejecutarse como máximo durante 30 segundos.
Facturación por filas leídas – pagas por cada fila que la consulta lee, no solo por las que devuelve. Recorrer por completo una tabla grande resulta caro, por lo que los buenos índices importan especialmente.
Sin funciones de SQLite a nivel de archivo – no se permiten ATTACH DATABASE, la carga de extensiones ni las escrituras en sqlite_master. Las claves foráneas siempre se aplican; en vez de PRAGMA foreign_keys = OFF, puedes usar PRAGMA defer_foreign_keys = on dentro de un lote.
Nombres reservados – las tablas que empiezan por _cf_ son internas de Cloudflare y no se pueden leer ni modificar.
Límites de la API REST – la API REST comparte los límites globales de la API de Cloudflare. Está destinada a la administración y las herramientas, no al tráfico de producción. Tu aplicación debe utilizar un binding de Worker.

Casos de uso habituales

D1 funciona especialmente bien cuando tu aplicación ya se ejecuta en Cloudflare o cuando los datos se dividen naturalmente en bases pequeñas e independientes:

Backends para Workers y Pages – cuentas de usuario, ajustes, contenido y pedidos de aplicaciones web que se ejecutan en el edge
Una base por cliente – cada cliente de una aplicación SaaS tiene su propia base aislada, lo que simplifica la separación, eliminación y exportación de datos
Almacenamiento de contenido y configuración – blogs, contenido de CMS, indicadores de funciones, redirecciones y otros datos con predominio de lecturas, idealmente servidos desde réplicas de lectura
Prototipos y proyectos pequeños – el nivel gratuito y la configuración mínima permiten empezar rápido y crecer después
Analítica y registros ligeros – contadores, eventos y registros de auditoría, siempre que cada base respete el límite de tamaño
Cachés de otros datos en el edge – una copia SQLite de datos seleccionados de tu base principal, cerca de los usuarios

D1 no es adecuada para una única base OLTP grande con muchas escrituras, cargas que necesitan transacciones interactivas largas ni archivos binarios grandes. Para esos casos convienen más PostgreSQL, MySQL u otra base de datos tradicional, posiblemente accesible mediante Cloudflare Hyperdrive.

Conectar DbGate a Cloudflare D1

DbGate se conecta a D1 mediante la API REST de Cloudflare. Cada conexión está vinculada a una cuenta de Cloudflare y muestra todas las bases D1 a las que puede acceder el token de API.

Paso 1 – Busca el ID de la cuenta

Inicia sesión en el panel de Cloudflare.
Abre Storage & Databases | D1 SQL Database, o la página de inicio de la cuenta.
Copia tu Account ID. Aparece en los detalles de la cuenta y en la URL del panel (dash.cloudflare.com/<account-id>/...).

Paso 2 – Crea un token de API

Ve a My Profile | API Tokens y haz clic en Create Token.
Elige Create Custom Token.
En Permissions, añade Account | D1 | Edit. Si solo necesitas leer datos, basta con Read.
En Account Resources, selecciona la cuenta que contiene tus bases.
Si quieres, limita el token a tu dirección IP y establece una fecha de caducidad.
Crea el token y cópialo. Cloudflare solo lo muestra una vez.

Utiliza un token dedicado para DbGate, de modo que puedas revocarlo sin afectar a los tokens de tus procesos de despliegue.

Paso 3 – Crea la conexión en DbGate

En DbGate, haz clic en New connection.
Selecciona Cloudflare D1 como tipo de conexión.
Rellena Cloudflare Account ID y Cloudflare API Token.
Deja Cloudflare API URL vacío salvo que necesites un endpoint personalizado. La dirección predeterminada es https://api.cloudflare.com/client/v4.
Si tu red lo requiere, configura un proxy HTTP en los ajustes de la conexión.
Si quieres evitar cambios accidentales, marca Is read only.
Haz clic en Test y después en Save (o Connect).

Después de conectarte, DbGate muestra todas las bases D1 de la cuenta accesibles para el token. Despliega una base para ver sus tablas y vistas, además de sus columnas, índices y claves foráneas.

Si la conexión falla, DbGate intenta indicar la causa: token no válido o caducado, falta de permiso para D1, ID de cuenta incorrecto o base que ya no existe.

Administrar D1 desde DbGate

Internamente, DbGate trata D1 como SQLite con un transporte diferente. El explorador de datos, la generación de SQL y el análisis del esquema funcionan igual que con los archivos SQLite locales, por lo que casi todo lo que ya conoces sigue siendo válido.

Explorar y editar datos

Abre cualquier tabla en el explorador de datos para filtrar, ordenar y buscar filas, seguir claves foráneas hasta registros relacionados o editar valores directamente en la cuadrícula. Los cambios se escriben en D1 al guardarlos.

Como D1 cobra por las filas leídas, utiliza filtros y columnas indexadas al explorar tablas grandes, en lugar de desplazarte por todos los datos.

Explorar el esquema

DbGate carga toda la estructura de la base: tablas, columnas, claves primarias y foráneas, índices y vistas. Cada consulta a D1 implica una solicitud HTTPS, así que DbGate planifica el análisis del esquema y lo envía en unas pocas solicitudes por lotes, en vez de cientos de consultas individuales. Una base de tamaño normal solo necesita dos solicitudes para un análisis completo.

Las tablas internas _cf_* de Cloudflare se ocultan en el esquema para que solo veas tus propios objetos.

Ejecutar consultas SQL

Abre el editor de consultas de una base D1 y escribe SQL de SQLite como siempre, con autocompletado basado en el esquema cargado. Cuando ejecutas un script con varias sentencias, DbGate las envía a D1 como un solo lote. D1 lo ejecuta de forma atómica: el script se completa entero o no se ejecuta nada.

Ten en cuenta lo siguiente:

Las sentencias explícitas BEGIN, COMMIT, ROLLBACK y SAVEPOINT se rechazan con un mensaje claro, porque la API de D1 no permite transacciones interactivas. Los botones de transacción se ocultan en las conexiones D1.
En una conexión marcada como Is read only, DbGate solo permite SELECT, EXPLAIN y sentencias PRAGMA que leen el esquema. Todo lo demás se rechaza antes de enviarlo a Cloudflare. Para mayor protección, usa también un token con el permiso D1 | Read.
EXPLAIN QUERY PLAN muestra si una consulta utiliza un índice o recorre toda la tabla, lo que afecta directamente al coste de D1.

Exportar e importar datos

Puedes exportar resultados de consultas y tablas a CSV, Excel, JSON y otros formatos compatibles con DbGate, e importar archivos a tablas D1. Es útil para correcciones puntuales, informes o traslados de datos entre D1 y otras bases conectadas a DbGate.

Crear una copia de seguridad de D1

Time Travel te protege frente a errores durante el periodo de retención, pero no te proporciona un archivo que puedas conservar, archivar o abrir en otro lugar. DbGate puede respaldar una base D1 en un archivo SQL sencillo:

Haz clic con el botón derecho en la base dentro del árbol de conexiones.
Elige Create database backup.
Selecciona qué incluir: esquema, datos, ajustes de la base y rowids, las mismas opciones que en una copia de seguridad de SQLite local.
Inicia la copia de seguridad.

El resultado es un script SQL de SQLite normal. Puedes restaurarlo en otra base D1, abrirlo con la herramienta de línea de comandos sqlite3 o cargarlo en un archivo SQLite local para desarrollo y depuración.

Restaurar en D1

DbGate también puede restaurar un volcado SQL en una base D1, ya sea una copia creada por DbGate o un volcado SQLite de otra fuente. Haz clic con el botón derecho en la base de destino, selecciona Restore database backup y elige el archivo SQL.

Como D1 no acepta el volcado tal cual, DbGate lo adapta durante la restauración:

El volcado se envía en lotes de hasta 250 sentencias (y como máximo 1 MB). Cada lote se ejecuta como una transacción D1, por lo que un lote fallido no deja escrituras parciales.
Se omiten las sentencias de transacción del volcado, ya que cada lote tiene su propia transacción.
Las claves foráneas se difieren hasta el final de cada lote mediante PRAGMA defer_foreign_keys = on, como recomienda Cloudflare para las importaciones.
Se omiten los objetos cuyos nombres reservados empiezan por _cf_.
Las sentencias que D1 podría rechazar, como contadores AUTOINCREMENT, estadísticas o user_version, se ejecutan después de los datos y los problemas solo se notifican como advertencias.
Si está activado Stop on first error, la restauración se detiene en el primer lote fallido; de lo contrario continúa e informa de todos los errores al final.

Hay dos cosas que no se pueden restaurar mediante la API SQL de D1: filas cuya sentencia INSERT supera el límite de 100 KB de D1 (normalmente por texto o BLOB grandes), y tablas virtuales que un volcado recrea con PRAGMA writable_schema. DbGate las señala claramente en lugar de fallar en silencio.

La combinación de copia y restauración también permite trasladar una base SQLite local a D1: crea una copia del archivo local con DbGate y restaura el archivo SQL en una base D1 vacía. También funciona a la inversa, por ejemplo para copiar datos de producción de D1 a un archivo SQLite local para pruebas.

No se permite restaurar mediante una conexión de solo lectura.

Notas de seguridad

El token de API se guarda con la conexión, como las demás credenciales de DbGate. No lo compartas y procura limitarlo a permisos D1, una sola cuenta y, si es posible, tu dirección IP.
DbGate garantiza que el token nunca aparezca en registros ni mensajes de error.
En DbGate Team Premium puedes definir la conexión D1 una sola vez en el servidor y controlar qué usuarios y roles pueden utilizarla, en lugar de repartir el token entre todos los miembros del equipo.

Conclusión

Cloudflare D1 facilita dar a cada Worker, proyecto o cliente su propia base SQL. DbGate simplifica el trabajo con esas bases: con un ID de cuenta y un token de API obtienes exploración del esquema, una cuadrícula editable, editor SQL, importación y exportación, y copias de seguridad y restauración. Todo ello en la misma herramienta que ya utilizas para PostgreSQL, MySQL, SQL Server, SQLite y muchas otras bases de datos.

Descarga DbGate y pruébalo con tus bases D1.