Límites de D1 y cuándo Hyperdrive

Cada tecnología dibuja, con sus límites, la forma de los problemas que resuelve bien. D1 no es una base pequeña: es una apuesta arquitectónica por muchas bases pequeñas en lugar de una gigante. Sus números —diez gigabytes por base como techo infranqueable, un solo hilo de ejecución— no son carencias que Cloudflare no ha tenido tiempo de arreglar, sino el contorno de un modelo. Entenderlos te dice cuándo D1 es la herramienta perfecta y cuándo tu problema pide, en realidad, un Postgres detrás de Hyperdrive.

El tamaño y su techo

Una base D1 almacena hasta 10 GB en el plan de pago, y ese número, a diferencia de casi todos los límites de la plataforma, no se puede subir por solicitud: es un tope de diseño. Lo que sí es enorme es la cantidad de bases: 50.000 por cuenta de partida —ampliable a millones—, con hasta 1 TB de almacenamiento agregado. La asimetría es el mensaje. Cloudflare no te invita a hacer una base grande; te invita a hacer muchísimas pequeñas.

Cada tabla admite hasta 100 columnas, cada fila o BLOB hasta 2 MB, cada sentencia SQL hasta 100 KB y cada consulta hasta 100 parámetros ligados. Son límites holgados para el grano que D1 espera —una base por usuario, por inquilino, por entidad— y estrechos para quien intenta meter un monolito relacional dentro.

Cada uno de estos números es, en realidad, una pregunta disfrazada. El tope de 2 MB por fila pregunta si de verdad ese blob pertenece a la base o a R2; el de 100 columnas, si esa tabla ancha no son en realidad varias entidades sin normalizar; el de 100 KB por sentencia, si esa consulta gigante no debería ser un lote. Los límites de D1 empujan, con suavidad, hacia esquemas y accesos sanos.

Un solo hilo

El hecho técnico que gobierna el rendimiento de D1 es que cada base está respaldada por un único Durable Object y procesa las consultas de una en una. No hay paralelismo dentro de una base: es un hilo. De ahí sale una fórmula sorprendentemente simple para el rendimiento: tu caudal máximo es el inverso de la duración media de tus consultas.

consulta media de 1 ms    ->  cerca de 1000 consultas por segundo
consulta media de 100 ms  ->  cerca de 10 consultas por segundo

Si las consultas se agolpan más rápido de lo que se pueden procesar, D1 las encola; si la cola se llena, devuelve un error de sobrecarga. Por eso el rendimiento en D1 no se compra con más CPU, se gana con consultas más cortas: índices adecuados, sentencias afiladas, lotes bien pensados. La replicación de lectura escala las lecturas repartiéndolas entre réplicas, pero cada réplica es también de un solo hilo, y toda escritura sigue embudada en la primaria.

Conviene ver este número no como un castigo sino como un contrato de rendimiento honesto. Una base tradicional oculta su contención tras un pool de hilos y un planificador; D1 la expone: si tus consultas son lentas, tu caudal cae de forma visible y predecible, y la solución está siempre en el mismo sitio, la consulta. Medir la duración media de tus sentencias deja de ser un ejercicio académico para volverse la métrica que gobierna cuántos usuarios concurrentes puede servir una base.

Esa aritmética también explica por qué la replicación de lectura importa tanto justo aquí: no acelera una consulta individual, pero multiplica el número de hilos que pueden atender lecturas a la vez, uno por réplica. El techo de escritura sigue siendo el hilo único de la primaria; el de lectura se reparte. Saber cuál de los dos es tu cuello de botella —lecturas o escrituras— decide si la replicación te ayuda o si tu problema tiene otra forma. En D1, medir precede a optimizar, y casi siempre la optimización es la misma: acortar la consulta.

Diseñar dentro de los límites

El error clásico al llegar a D1 desde Postgres es tratarlo como un Postgres pequeño y chocar contra el techo de 10 GB. El diseño correcto invierte el grano: si tu SaaS tiene inquilinos, dale a cada uno su base; si tu app es por usuario, una base por usuario. Miles o millones de bases de 10 GB, cada una de un solo hilo, escalan de forma horizontal y sin coste por existir, porque pagas por consultas y almacenamiento, no por base.

Este patrón —sharding por entidad— convierte los límites en virtudes. El aislamiento entre inquilinos es físico, no lógico; el replica lag de un cliente no afecta a otro; una restauración con Time Travel toca a un solo inquilino. Lo que en una base monolítica serían problemas de contención y de radio de impacto, aquí se disuelven porque el grano es fino.

Nótese además que la replicación y Time Travel, de las lecciones anteriores, escalan con este grano: replicar mil bases pequeñas cerca de sus usuarios y restaurar una sola sin tocar a las demás son operaciones baratas justamente porque cada base es pequeña. Los límites de D1 no viven aislados; conspiran a favor del mismo modelo horizontal.

Hay un caso que este diseño no elude, y conviene decirlo con claridad: si tu problema es intrínsecamente una sola entidad enorme —un grafo social único, un libro mayor contable global, un índice compartido por todos—, partirlo en bases por inquilino no tiene sentido, porque no hay inquilinos que separar. Forzar ese caso en D1 te obliga a coser consultas entre bases a mano, reinventando mal lo que un motor relacional grande ya hace bien. Reconocer esa frontera es parte de la competencia.

Cuándo Hyperdrive

Hay problemas que no encajan en el grano de D1: una base relacional que supera los 10 GB y no se deja partir, un esquema que ya vive en Postgres con extensiones y tipos de los que dependes, una carga de escritura que un solo hilo no absorbe, o simplemente un equipo con años de SQL de Postgres que no va a reescribir. Para eso está Hyperdrive: no es una base, es un acelerador que pone tu Postgres o MySQL existente —esté en AWS, Neon, PlanetScale o donde sea— al alcance de un Worker con baja latencia.

import { Client } from "pg";

export default {
  async fetch(request, env) {
    // Hyperdrive mantiene el pool; crear el cliente en cada peticion es barato
    const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
    await client.connect();
    const { rows } = await client.query("SELECT * FROM productos LIMIT 20");
    return Response.json(rows);
  },
};

Lo hace con dos mecanismos. Un pool de conexiones global elimina el coste de abrir una conexión nueva en cada invocación, que para una base regional accedida desde el edge sería demoledor. Y una caché de consultas, activa por defecto, sirve las lecturas más populares sin ir hasta el origen. Sigues usando tus drivers y tu ORM de siempre; Hyperdrive se interpone y los vuelve viables desde el edge.

El binding se declara en la configuración de Wrangler, y a partir de ahí env.HYPERDRIVE expone la conexión que tu driver consume:

{
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "tu-id-de-hyperdrive",
      "localConnectionString": "postgres://usuario:clave@localhost:5432/midb"
    }
  ]
}

La honestidad intelectual aquí vale más que la lealtad a una herramienta: no todo pertenece a D1, y saber cuándo salir de él es tan parte del oficio como saber usarlo bien.

El criterio de elección, al final, se reduce a una sola pregunta sobre la forma del dato:

flowchart TD
Q[como es tu problema de datos] --> A[muchas entidades pequenas y aisladas]
Q --> B[una masa relacional central y grande]
A --> D1[D1 con sharding por entidad]
B --> C[ya vive o debe vivir en postgres o mysql]
C --> HY[Hyperdrive lo acelera desde el edge]
style D1 fill:#a6e3a1,color:#11111b
style HY fill:#89b4fa,color:#11111b