Utiliser Cloudflare Workers avec ClickHouse Managed Postgres

Les Cloudflare Workers exécutent votre code sur le réseau de Cloudflare, et Hyperdrive maintient un pool de connexions entre ce réseau et votre base de données, ce qui évite à chaque requête le coût d’une nouvelle négociation TCP et TLS. Dans ce guide, vous allez créer une configuration Hyperdrive qui vérifie le certificat de votre instance, développer un Worker TypeScript qui crée et lit des lignes avec node-postgres (pg), l’exécuter localement avec wrangler dev, puis le déployer sur workers.dev.

Prérequis

Un compte Cloudflare. Hyperdrive est disponible avec les offres Workers Free et Paid.
Node.js 20 ou une version ultérieure. Ce guide a été testé avec Node.js 24.21.0, Wrangler 4.145.0, create-cloudflare 2.73.1, pg 8.23.1 et Postgres 18.
Un compte ClickHouse Cloud.
psql, pour créer la base de données et la table. Vous pouvez également exécuter les instructions SQL dans la console SQL.

Créer un service ClickHouse Managed Postgres

Dans la console ClickHouse Cloud, cliquez sur New service et sélectionnez Postgres. L’instance est prête en quelques minutes. Pour une présentation pas à pas, consultez le guide de démarrage rapide.

Obtenir vos informations de connexion

Cliquez sur Connect dans la barre latérale gauche de votre service. Laissez Directly sélectionné et activez Use SSL. L’URL se termine alors par sslmode=verify-full&sslrootcert=<service-name>-ca-certificate.pem. Cliquez sur Download CA certificate pour télécharger le certificat CA de votre instance. Vous pouvez également le télécharger depuis Settings → CA Certificate. Ce guide fait pointer Hyperdrive vers la connexion directe sur le port 5432, et non vers le PgBouncer intégré sur le port 6432 :

Hyperdrive est lui-même un pooler de connexions fonctionnant en mode transaction. Il maintient un petit pool de connexions persistantes vers votre base de données et les partage entre toutes les requêtes des Workers, un rôle qui reviendrait sinon à PgBouncer. Cloudflare recommande de fournir à Hyperdrive une chaîne de connexion directe plutôt qu’une chaîne passant par un pool.
Il est également possible de faire pointer Hyperdrive vers le port 6432, mais enchaîner deux poolers en mode transaction ajoute un saut réseau et un second niveau de réglage de la taille des pools, sans apporter de capacité supplémentaire.
Hyperdrive ouvre au maximum environ 20 connexions par configuration avec l’offre Workers Free, et environ 100 avec l’offre Paid, ce qui reste en deçà de la valeur par défaut de max_connections, fixée à 500. Si vous avez plusieurs configurations Hyperdrive ou d’autres clients sur la même instance, additionnez leurs connexions et, si nécessaire, ajustez max_connections dans Settings ou la limite de connexions à l’origine dans Hyperdrive.

Si vous utilisez une liste d’accès IP, Hyperdrive se connecte depuis les plages d’adresses IP de Cloudflare, qui doivent donc être autorisées.

Créer la base de données

Renommez le certificat téléchargé en ca-certificate.pem. Créez ensuite une base de données et une table notes. Remplacez <PASSWORD> et l’hôte par les valeurs affichées dans la fenêtre modale Connect :

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

Créer le projet Worker

Créez un Worker TypeScript à partir du modèle « Hello World » avec create-cloudflare, puis installez 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

Vous l’ajoutez à une application existante ?Ignorez npm create cloudflare. Dans votre projet Worker, exécutez npm install pg et npm install -D @types/pg, puis passez directement à Créer une configuration Hyperdrive, qui ajoute le binding Hyperdrive, et à Configurer le Worker, qui active nodejs_compat.

Déplacez ca-certificate.pem dans le répertoire de votre projet. Si vous n’avez jamais utilisé Wrangler, exécutez npx wrangler login pour l’autoriser à accéder à votre compte Cloudflare.

Créer une configuration Hyperdrive

Hyperdrive chiffre toujours la connexion à votre base de données, mais par défaut, il ne vérifie pas le certificat auprès de l’autorité de certification (CA) de votre instance. Pour obtenir l’équivalent de sslmode=verify-full, commencez par téléverser le certificat CA dans votre compte 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>

Utilisez l’ID indiqué dans la sortie pour créer la configuration Hyperdrive. La chaîne de connexion utilise le port 5432 et la base de données guide_cloudflare, sans aucun paramètre SSL ; ce sont les options --sslmode et --ca-certificate-id qui configurent TLS :

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 connecte à votre base de données lors de la création de la configuration. Avec --sslmode verify-full, il vérifie que le certificat du serveur est signé par l’autorité de certification (CA) que vous avez téléversée et qu’il correspond au nom d’hôte. Si l’une de ces vérifications échoue, la commande échoue avec une erreur telle que cert verification failed - unable to get local issuer certificate et aucune configuration n’est créée. Le mot de passe est stocké dans la configuration Hyperdrive de votre compte Cloudflare, et non dans votre projet. --binding HYPERDRIVE --update-config ajoute la configuration à wrangler.jsonc, ce qui permet à votre Worker d’y accéder via env.HYPERDRIVE. Si votre projet utilise wrangler.toml, Wrangler ne modifie pas le fichier : collez-y vous-même l’extrait [[hyperdrive]] affiché par la commande.

Mise en cache des requêtesHyperdrive peut mettre en cache les résultats des requêtes de lecture, pendant 60 secondes par défaut. Ce guide désactive la mise en cache avec --caching-disabled, de sorte qu’une lecture effectuée juste après une écriture renvoie bien la nouvelle ligne. Pour les requêtes majoritairement en lecture qui tolèrent des résultats légèrement obsolètes, vous pouvez créer une seconde configuration avec la mise en cache activée et lier les deux. Consultez Mise en cache des requêtes.

Configurer le Worker

pg nécessite la couche de compatibilité Node.js. Ouvrez wrangler.jsonc et ajoutez l’indicateur nodejs_compat à côté de compatibility_date. La section concernée du fichier se présente alors comme suit :

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 vous utilisez un fichier wrangler.toml, ajoutez plutôt compatibility_flags = ["nodejs_compat"] sous compatibility_date. Si le fichier contient déjà compatibility_flags, ajoutez nodejs_compat à la liste. Régénérez les types TypeScript afin que env.HYPERDRIVE soit typé :

npx wrangler types

Si votre projet utilise encore le paquet @cloudflare/workers-types, wrangler types indique comment migrer vers les types générés.

Interroger la base de données

Remplacez src/index.ts par un Worker qui crée une note via POST /notes et renvoie la liste de toutes les notes via GET /notes. Si vous disposez déjà d’un Worker, ajoutez plutôt cette même gestion de /notes à votre 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 pointe vers Hyperdrive, et non vers votre instance. La liaison entre le Worker et Hyperdrive reste interne à Cloudflare ; elle ne nécessite donc aucun paramètre SSL. C’est Hyperdrive qui gère la connexion TLS vérifiée vers Postgres.

Hyperdrive fonctionne en mode transaction, à la manière de PgBouncer : chaque transaction peut utiliser une connexion différente vers Postgres. Les requêtes paramétrées, les transactions et les prepared statements nommés de pg sont tous pris en charge. Ne comptez pas sur l’état de session, par exemple un SET au niveau de la session, d’une requête à l’autre ; utilisez plutôt SET LOCAL au sein d’une transaction.

Exécution en local

wrangler dev exécute le Worker sur votre machine. En local, Hyperdrive ne gère pas de pool de connexions ; le binding se connecte directement à la base de données indiquée dans CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>. Affectez à cette variable la chaîne de connexion directe, avec sslmode=verify-full et le path du certificat CA, puis démarrez le 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 gère le TLS pour la connexion locale. sslrootcert est résolu par rapport au répertoire depuis lequel vous lancez wrangler dev.

Si vous omettez sslmode, la connexion locale n’est pas chiffrée. Avec sslmode=require, elle est chiffrée, mais le certificat n’est pas vérifié. Utilisez toujours sslmode=verify-full avec sslrootcert. Si le certificat de l’autorité de certification (CA) est absent ou incorrect, les requêtes échouent avec l’erreur Connection terminated unexpectedly.

Dans un second terminal, créez une note :

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"}

Affichez la liste des notes :

curl http://localhost:3108/notes

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

pg renvoie les colonnes bigint sous forme de chaînes de caractères : id vaut donc "1" et non 1.

Déploiement

Déployez le 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

S’il s’agit de votre premier Worker, Wrangler vous invite à enregistrer un sous-domaine workers.dev. Créez une note à l’aide du Worker déployé :

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"}

Ouvrez https://hyperdrive-notes.<your-subdomain>.workers.dev/notes dans votre navigateur pour afficher les deux notes. La réponse se présente comme suit :

[{"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"}]

Vérifier dans la console

Ouvrez la console SQL dans la barre latérale gauche de votre service, développez guide_cloudflare, puis public, et cliquez sur la table notes. Les deux notes s’affichent :

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

Nettoyage

Pour supprimer les ressources créées dans votre compte Cloudflare, supprimez le Worker, la configuration Hyperdrive et le certificat CA :

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

Si wrangler cert delete renvoie Certificate cannot be deleted while in use, attendez une minute après avoir supprimé la configuration Hyperdrive, puis relancez la commande.

Étapes suivantes

Connexion : chaînes de connexion, PgBouncer et TLS
Paramètres : paramètres Postgres tels que max_connections
Répliques en lecture : faire évoluer la capacité de lecture
Documentation Hyperdrive : mise en cache des requêtes, optimisation du pool de connexions et observability

Premiers pas

Fonctionnalités

Guides

Tarification

Intégration ClickHouse

Migrations

Supervision

FAQ

Utiliser Cloudflare Workers avec ClickHouse Managed Postgres

Prérequis

Créer un service ClickHouse Managed Postgres

Obtenir vos informations de connexion

Créer la base de données

Créer le projet Worker

Créer une configuration Hyperdrive

Configurer le Worker

Interroger la base de données

Exécution en local

Déploiement

Vérifier dans la console

Nettoyage

Étapes suivantes

​Prérequis

​Créer un service ClickHouse Managed Postgres

​Obtenir vos informations de connexion

​Créer la base de données

​Créer le projet Worker

​Créer une configuration Hyperdrive

​Configurer le Worker

​Interroger la base de données

​Exécution en local

​Déploiement

​Vérifier dans la console

​Nettoyage

​Étapes suivantes

Prérequis

Créer un service ClickHouse Managed Postgres

Obtenir vos informations de connexion

Créer la base de données

Créer le projet Worker

Créer une configuration Hyperdrive

Configurer le Worker

Interroger la base de données

Exécution en local

Déploiement

Vérifier dans la console

Nettoyage

Étapes suivantes