Configurar y conectar: de la cadena al primer SELECT

La teoría de Hyperdrive es más difícil que su práctica. Una vez entendidos el pool y la caché, ponerlo en marcha son cuatro pasos cortos: crear una configuración que guarde la cadena de conexión a tu base, declararla como binding, activar la compatibilidad con Node porque los drivers de Postgres la necesitan, y escribir el mismo SQL de siempre con el driver de siempre. Lo único que cambia respecto a tu código actual es de dónde sale la cadena de conexión, y ese detalle diminuto es también el que reordena por completo el modelo de seguridad.

Crear la configuración

Una configuración de Hyperdrive es un objeto en tu cuenta que guarda cómo llegar a tu base y con qué credenciales. Se crea una sola vez, con los datos que ya tienes: la dirección o el nombre de máquina, el puerto, el usuario, la contraseña y el nombre de la base. Casi todos los proveedores te dan esa información ya montada en la cadena de conexión estándar que los drivers entienden.

# Postgres: postgres://USUARIO:CLAVE@MAQUINA:PUERTO/BASE
npx wrangler hyperdrive create mi-postgres \
  --connection-string="postgres://usuario:clave@db.ejemplo.com:5432/produccion"

# MySQL: mysql://USUARIO:CLAVE@MAQUINA:PUERTO/BASE
npx wrangler hyperdrive create mi-mysql \
  --connection-string="mysql://usuario:clave@db.ejemplo.com:3306/produccion"

Si todo va bien, el comando imprime la configuración recién creada con el único dato que necesitas conservar: el id.

{
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "57b7076f58be42419276f058a8968187"
    }
  ]
}

Fíjate en lo que no aparece ahí: tu usuario y tu contraseña. Se quedaron dentro de la configuración, en la plataforma, y no vuelven a salir. A partir de este momento tu proyecto conoce un identificador opaco, no unas credenciales, y esa es la primera consecuencia práctica del modelo de bindings aplicado a una base tradicional.

El binding y nodejs_compat

Con el identificador en la mano, el binding se declara en wrangler.jsonc igual que cualquier otro recurso. El nombre que elijas es el que aparecerá en env, y debe ser un identificador válido de JavaScript.

{
  "name": "mi-api",
  "main": "src/index.ts",
  "compatibility_date": "2026-06-25",
  "compatibility_flags": ["nodejs_compat"],
  "observability": { "enabled": true },
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "57b7076f58be42419276f058a8968187"
    }
  ]
}

La línea que más gente olvida es nodejs_compat, y su ausencia produce un error desconcertante en tiempo de ejecución que habla de un módulo node: que no existe. La razón es sencilla en cuanto se piensa: a diferencia de D1 o KV, aquí no usas una API de la plataforma sino un driver de base de datos real, escrito para Node, que abre un socket, maneja búferes y emite eventos. Ese driver necesita que el runtime le ofrezca las APIs de Node que da por hechas, y esa es exactamente la bandera que las enciende. Sin ella no falla la configuración: falla el import de tu driver.

Consultar con el driver de siempre

Instalado el driver, el código es indistinguible del que escribirías contra tu base directa. Con postgres.js —recomendado en versión 3.4.5 o posterior— basta con pasar la cadena que el binding expone.

import postgres from "postgres";

export interface Env {
  HYPERDRIVE: Hyperdrive;
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    // un cliente nuevo por peticion es barato: el pool lo mantiene Hyperdrive
    const sql = postgres(env.HYPERDRIVE.connectionString);
    try {
      const filas = await sql`SELECT id, nombre, precio FROM productos LIMIT 20`;
      return Response.json(filas);
    } catch (e) {
      console.error(e);
      return Response.json({ error: String(e) }, { status: 500 });
    }
  },
} satisfies ExportedHandler<Env>;

El comentario del código señala el cambio de hábito más importante al venir de un backend clásico. Allí, crear un cliente en cada petición era un pecado de rendimiento; aquí es lo correcto, porque el pool ya no vive en tu proceso sino en Hyperdrive, y tu cliente es una envoltura ligera sobre una conexión que se establece a milisegundos de distancia. No intentes conservar clientes entre invocaciones: el isolate que los guardaría puede desaparecer en cualquier momento.

Con node-postgres el patrón es el mismo cambiando la fachada, y con MySQL el binding expone además los campos por separado, porque mysql2 los prefiere así y necesita una opción extra para no recurrir a evaluación dinámica de código, que el runtime no permite.

import { createConnection } from "mysql2/promise";

const conexion = await createConnection({
  host: env.HYPERDRIVE.host,
  user: env.HYPERDRIVE.user,
  password: env.HYPERDRIVE.password,
  database: env.HYPERDRIVE.database,
  port: env.HYPERDRIVE.port,
  disableEval: true, // obligatorio en Workers: sin eval en el analizador
});

Tu ORM entra por la misma puerta. Drizzle, Prisma o Kysely se apoyan por debajo en estos mismos drivers, así que reciben la cadena o el cliente y siguen funcionando sin saber que hay un acelerador de por medio. El tipo Hyperdrive de la interfaz Env lo genera wrangler types a partir de tu configuración, de modo que el editor te avisa si escribes mal el nombre del binding.

flowchart LR
CFG[wrangler hyperdrive create] --> ID[id de configuracion]
ID --> BIND[binding en wrangler.jsonc]
BIND --> ENV[env.HYPERDRIVE en el Worker]
ENV --> DRV[driver postgres o mysql]
DRV --> DB[tu base existente]
style ENV fill:#89b4fa,color:#11111b
style DB fill:#a6e3a1,color:#11111b

Desarrollo local

En local no hay pool ni caché de Cloudflare que valga: tu Worker se conecta directamente a una base que tú le indiques. Ese destino se declara con localConnectionString junto al binding, o con una variable de entorno cuyo nombre termina con el nombre del binding.

{
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "57b7076f58be42419276f058a8968187",
      "localConnectionString": "postgres://usuario:clave@localhost:5432/desarrollo"
    }
  ]
}

# alternativa por variable de entorno, con el nombre del binding al final
export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://usuario:clave@localhost:5432/desarrollo"
npx wrangler dev

Desde finales de 2025 ese destino puede ser también una base remota con TLS, indicando el modo correspondiente en la cadena —sslmode=require para Postgres, sslMode=REQUIRED para MySQL—, lo que permite desarrollar contra la base real sin renunciar a ejecutar el código en tu máquina.

Hay una diferencia de comportamiento que conviene tener presente para no sacar conclusiones falsas: con wrangler dev la caché de consultas no actúa. Todo lo que midas en local será el rendimiento sin caché. Si quieres comprobar el efecto real de la caché contra tu configuración desplegada, wrangler dev --remote ejecuta el Worker en la red de Cloudflare, con la contrapartida de que ya no corre en tu máquina.