Uso de Cloudflare Workers con ClickHouse Managed Postgres

Cloudflare Workers ejecuta su código en la red de Cloudflare, e Hyperdrive mantiene un grupo de conexiones desde esa red hasta su base de datos, de modo que no sea necesario pagar el coste de un nuevo handshake TCP y TLS en cada solicitud. En esta guía, creará una configuración de Hyperdrive que verifica el certificado de su instancia, desarrollará un Worker en TypeScript que crea y lee filas con node-postgres (pg), lo ejecutará localmente con wrangler dev y lo desplegará en workers.dev.

Requisitos previos

Una cuenta de Cloudflare. Hyperdrive está disponible en los planes Workers Free y Workers Paid.
Node.js 20 o posterior. Esta guía se probó con Node.js 24.21.0, Wrangler 4.145.0, create-cloudflare 2.73.1, pg 8.23.1 y Postgres 18.
Una cuenta de ClickHouse Cloud.
psql, para crear la base de datos y la tabla. También puede ejecutar las sentencias SQL en la consola SQL.

Crear un servicio de ClickHouse Managed Postgres

En la consola de ClickHouse Cloud, haga clic en New service y seleccione Postgres. La instancia estará lista en unos minutos. Consulte la guía de inicio rápido para ver el proceso paso a paso.

Obtener los detalles de conexión

Haga clic en Conectar en la barra lateral izquierda de su servicio. Mantenga seleccionada la opción Directly y active Use SSL. La URL terminará entonces en sslmode=verify-full&sslrootcert=<service-name>-ca-certificate.pem. Haga clic en Download CA certificate para descargar el certificado de CA de su instancia. También puede descargarlo desde Settings → CA Certificate. En esta guía, Hyperdrive apunta a la conexión directa en el puerto 5432, no al PgBouncer incluido en el puerto 6432:

Hyperdrive es en sí mismo un agrupador de conexiones que funciona en modo transacción. Mantiene un pequeño grupo de conexiones de larga duración con su base de datos y las comparte entre todas las solicitudes de los Workers, que es precisamente la tarea que, de lo contrario, realizaría PgBouncer. Cloudflare recomienda proporcionar a Hyperdrive una cadena de conexión directa en lugar de una agrupada.
Apuntar Hyperdrive al puerto 6432 también funciona, pero encadenar dos agrupadores en modo transacción añade un salto de red adicional y un segundo punto donde ajustar el tamaño de los grupos, sin aportar más capacidad.
Hyperdrive abre como máximo unas 20 conexiones por configuración en el plan Workers Free y unas 100 en el plan Paid, lo que cabe holgadamente dentro del valor predeterminado de max_connections, que es 500. Si tiene varias configuraciones de Hyperdrive u otros clientes en la misma instancia, sume sus conexiones y, si es necesario, ajuste max_connections en Settings o el límite de conexiones de origen en Hyperdrive.

Si utiliza una lista de acceso por IP, tenga en cuenta que Hyperdrive se conecta desde los rangos de IP de Cloudflare, por lo que debe permitirlos.

Crear la base de datos

Cambie el nombre del certificado descargado a ca-certificate.pem. A continuación, cree una base de datos y una tabla notes. Sustituya <PASSWORD> y el host por los valores que aparecen en el cuadro de diálogo Conectar:

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_cloudflare;"

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE TABLE notes (id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, content text NOT NULL, created_at timestamptz NOT NULL DEFAULT now());"

CREATE TABLE

Crear el proyecto de Worker

Cree un Worker de TypeScript a partir de la plantilla “Hello World” con create-cloudflare e instale pg:

npm create cloudflare@latest -- hyperdrive-notes --type=hello-world --lang=ts --no-deploy
cd hyperdrive-notes
npm install pg
npm install -D @types/pg

¿Va a añadirlo a una aplicación existente?Omita npm create cloudflare. En su proyecto de Worker, ejecute npm install pg y npm install -D @types/pg y, luego, continúe con Crear una configuración de Hyperdrive, que añade la vinculación de Hyperdrive, y con Configurar el Worker, que habilita nodejs_compat.

Mueva ca-certificate.pem al directorio de su proyecto. Si es la primera vez que usa Wrangler, ejecute npx wrangler login para autorizarlo con su cuenta de Cloudflare.

Crear una configuración de Hyperdrive

Hyperdrive siempre cifra la conexión con su base de datos, pero, de forma predeterminada, no verifica el certificado con la CA de su instancia. Para obtener un comportamiento equivalente a sslmode=verify-full, primero suba el certificado de CA a su cuenta de Cloudflare:

npx wrangler cert upload certificate-authority --ca-cert ca-certificate.pem --name managed-postgres-ca

Success! Uploaded CA Certificate managed-postgres-ca
ID: <CA_CERTIFICATE_ID>

Use el ID de la salida para crear la configuración de Hyperdrive. La cadena de conexión utiliza el puerto 5432 y la base de datos guide_cloudflare, sin parámetros SSL; TLS se configura mediante --sslmode y --ca-certificate-id:

npx wrangler hyperdrive create managed-postgres \
  --connection-string="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare" \
  --ca-certificate-id <CA_CERTIFICATE_ID> \
  --sslmode verify-full \
  --caching-disabled \
  --binding HYPERDRIVE \
  --update-config

✅ Created new Hyperdrive PostgreSQL config: <HYPERDRIVE_ID>

Hyperdrive se conecta a su base de datos mientras crea la configuración. Con --sslmode verify-full, comprueba que el certificado del servidor esté firmado por la CA que ha subido y que coincida con el nombre del host. Si alguna de estas comprobaciones falla, el comando termina con un error como cert verification failed - unable to get local issuer certificate y no se crea ninguna configuración. La contraseña se almacena en la configuración de Hyperdrive de su cuenta de Cloudflare, no en su proyecto. --binding HYPERDRIVE --update-config añade la configuración a wrangler.jsonc para que su Worker pueda acceder a ella como env.HYPERDRIVE. Si su proyecto usa wrangler.toml, Wrangler no modifica el archivo; en su lugar, pegue en él el fragmento [[hyperdrive]] que muestra el comando.

Almacenamiento en caché de consultasHyperdrive puede almacenar en caché los resultados de las consultas de lectura, de forma predeterminada durante 60 segundos. En esta guía, la caché se desactiva con --caching-disabled para que una lectura realizada justo después de una escritura devuelva la nueva fila. Para consultas con un uso intensivo de lectura que toleren resultados ligeramente desactualizados, puede crear una segunda configuración con la caché activada y vincular ambas. Consulte Almacenamiento en caché de consultas.

Configurar el Worker

pg necesita la capa de compatibilidad con Node.js. Abra wrangler.jsonc y agregue el indicador nodejs_compat junto a compatibility_date. La parte correspondiente del archivo quedará así:

wrangler.jsonc

{
	"name": "hyperdrive-notes",
	"main": "src/index.ts",
	"compatibility_date": "2026-09-26",
	"compatibility_flags": ["nodejs_compat"],
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<HYPERDRIVE_ID>"
		}
	]
}

Si usa un archivo wrangler.toml, agregue compatibility_flags = ["nodejs_compat"] debajo de compatibility_date. Si el archivo ya contiene compatibility_flags, agregue nodejs_compat a la lista. Vuelva a generar los tipos de TypeScript para que env.HYPERDRIVE tenga un tipo explícito:

npx wrangler types

Si su proyecto todavía utiliza el paquete @cloudflare/workers-types, wrangler types indica cómo migrar a los tipos generados.

Consultar la base de datos

Reemplace src/index.ts por un Worker que cree una nota con POST /notes y liste todas las notas con GET /notes. Si ya tiene un Worker, agregue ese mismo manejo de /notes a su handler fetch:

src/index.ts

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname !== "/notes") {
			return new Response("Not found", { status: 404 });
		}

		// Hyperdrive keeps the connections to Postgres, so a new client per request is cheap.
		const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
		await client.connect();

		try {
			if (request.method === "POST") {
				// Create
				const { content } = await request.json<{ content: string }>();
				const { rows } = await client.query(
					"INSERT INTO notes (content) VALUES ($1) RETURNING id, content, created_at",
					[content],
				);
				return Response.json(rows[0], { status: 201 });
			}

			// Read
			const { rows } = await client.query("SELECT id, content, created_at FROM notes ORDER BY id");
			return Response.json(rows);
		} finally {
			// Close the client after the response is sent.
			ctx.waitUntil(client.end());
		}
	},
} satisfies ExportedHandler<Env>;

env.HYPERDRIVE.connectionString apunta a Hyperdrive, no a su instancia. La conexión entre el Worker y Hyperdrive no sale de Cloudflare, por lo que no requiere parámetros SSL. Hyperdrive se encarga de la conexión TLS verificada con Postgres.

Hyperdrive funciona en modo de transacción, al igual que PgBouncer: cada transacción puede usar una conexión distinta a Postgres. Las consultas parametrizadas, las transacciones y las sentencias preparadas con nombre de pg funcionan sin problemas. No dependa del estado de la sesión entre consultas, como un SET a nivel de sesión; en su lugar, use SET LOCAL dentro de una transacción.

Ejecutar localmente

wrangler dev ejecuta el Worker en su máquina. En local, Hyperdrive no agrupa las conexiones: la vinculación se conecta directamente a la base de datos indicada en CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>. Asigne a esta variable la cadena de conexión directa con sslmode=verify-full y la ruta al certificado de la CA y, a continuación, inicie el Worker:

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_cloudflare?sslmode=verify-full&sslrootcert=ca-certificate.pem"
npx wrangler dev --port 3108

Found a non-empty CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE variable for binding. Hyperdrive will connect to this database during local development.
...
Ready on http://localhost:3108

Wrangler gestiona TLS para la conexión local. sslrootcert se resuelve de forma relativa al directorio desde el que ejecutas wrangler dev.

Si omites sslmode, la conexión local no se cifra. Con sslmode=require, se cifra, pero el certificado no se verifica. Usa siempre sslmode=verify-full junto con sslrootcert. Si falta la CA o no es la correcta, las solicitudes fallan con Connection terminated unexpectedly.

En otra terminal, crea una nota:

curl -X POST http://localhost:3108/notes -H "Content-Type: application/json" -d '{"content": "Hello from wrangler dev"}'

{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"}

Lista las notas:

curl http://localhost:3108/notes

[{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"}]

pg devuelve las columnas bigint como cadenas, así que id es "1" y no 1.

Despliegue

Despliega el Worker:

npx wrangler deploy

Your Worker has access to the following bindings:
Binding                                   Resource
env.HYPERDRIVE (<HYPERDRIVE_ID>)          Hyperdrive Config

Uploaded hyperdrive-notes (2.35 sec)
Deployed hyperdrive-notes triggers (0.76 sec)
  https://hyperdrive-notes.<your-subdomain>.workers.dev

Si este es tu primer Worker, Wrangler te pedirá que registres un subdominio workers.dev. Crea una nota mediante el Worker desplegado:

curl -X POST https://hyperdrive-notes.<your-subdomain>.workers.dev/notes -H "Content-Type: application/json" -d '{"content": "Hello from Hyperdrive"}'

{"id":"2","content":"Hello from Hyperdrive","created_at":"2026-09-30T16:58:39.733Z"}

Abra https://hyperdrive-notes.<your-subdomain>.workers.dev/notes en su navegador para ver ambas notas. La respuesta es similar a la siguiente:

[{"id":"1","content":"Hello from wrangler dev","created_at":"2026-09-30T16:58:16.232Z"},{"id":"2","content":"Hello from Hyperdrive","created_at":"2026-09-30T16:58:39.733Z"}]

Verificar en la consola

Abra consola SQL en la barra lateral izquierda de su servicio, expanda guide_cloudflare y, a continuación, public, y haga clic en la tabla notes. Aparecerán ambas notas:

id	content	created_at
1	Hello from wrangler dev	2026-09-30 16:58:16.232466+00
2	Hello from Hyperdrive	2026-09-30 16:58:39.733203+00

Limpieza

Para eliminar los recursos que creó en su cuenta de Cloudflare, borre el Worker, la configuración de Hyperdrive y el certificado de CA:

npx wrangler delete
npx wrangler hyperdrive delete <HYPERDRIVE_ID>
npx wrangler cert delete --name managed-postgres-ca

Si wrangler cert delete devuelve el error Certificate cannot be deleted while in use, espere un minuto tras eliminar la configuración de Hyperdrive y vuelva a ejecutar el comando.

Próximos pasos

Conexión: cadenas de conexión, PgBouncer y TLS
Configuración: parámetros de Postgres como max_connections
Réplicas de lectura: escalado del tráfico de lectura
Documentación de Hyperdrive: almacenamiento en caché de consultas, ajuste del grupo de conexiones y observabilidad

Primeros pasos

Funcionalidades

Guías

Precios

Integración con ClickHouse

Migraciones

Monitorización

Preguntas frecuentes

Uso de Cloudflare Workers con ClickHouse Managed Postgres

Requisitos previos

Crear un servicio de ClickHouse Managed Postgres

Obtener los detalles de conexión

Crear la base de datos

Crear el proyecto de Worker

Crear una configuración de Hyperdrive

Configurar el Worker

Consultar la base de datos

Ejecutar localmente

Despliegue

Verificar en la consola

Limpieza

Próximos pasos

​Requisitos previos

​Crear un servicio de ClickHouse Managed Postgres

​Obtener los detalles de conexión

​Crear la base de datos

​Crear el proyecto de Worker

​Crear una configuración de Hyperdrive

​Configurar el Worker

​Consultar la base de datos

​Ejecutar localmente

​Despliegue

​Verificar en la consola

​Limpieza

​Próximos pasos

Requisitos previos

Crear un servicio de ClickHouse Managed Postgres

Obtener los detalles de conexión

Crear la base de datos

Crear el proyecto de Worker

Crear una configuración de Hyperdrive

Configurar el Worker

Consultar la base de datos

Ejecutar localmente

Despliegue

Verificar en la consola

Limpieza

Próximos pasos