> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Utiliser Cloudflare Workers avec ClickHouse Managed Postgres

> Interroger ClickHouse Managed Postgres depuis un Cloudflare Worker via Hyperdrive, avec node-postgres, une connexion TLS vérifiée, le développement en local et un déploiement sur workers.dev

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Beta</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>Fonctionnalité en bêta</span>
        </a>;
};

<BetaBadge link="https://clickhouse.com/cloud/postgres" galaxyTrack={true} galaxyEvent="docs.managed-postgres.guides-cloudflare-workers-beta" />

Les [Cloudflare Workers](https://developers.cloudflare.com/workers/) exécutent votre code sur le réseau de Cloudflare, et [Hyperdrive](https://developers.cloudflare.com/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`](https://node-postgres.com/) (`pg`), l'exécuter localement avec `wrangler dev`, puis le déployer sur `workers.dev`.

<h2 id="prerequisites">
  Prérequis
</h2>

* Un [compte Cloudflare](https://dash.cloudflare.com/sign-up). Hyperdrive est disponible avec les offres Workers Free et Paid.
* [Node.js](https://nodejs.org/) 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`](https://www.postgresql.org/download/), pour créer la base de données et la table. Vous pouvez également exécuter les instructions SQL dans la [console SQL](/fr/integrations/connectors/sql-clients/sql-console).

<h2 id="create-service">
  Créer un service ClickHouse Managed Postgres
</h2>

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](/fr/products/managed-postgres/quickstart).

<h2 id="connection-details">
  Obtenir vos informations de connexion
</h2>

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](/fr/products/managed-postgres/settings) ou la limite de connexions à l'origine dans Hyperdrive.

<Note>
  Si vous utilisez une [liste d'accès IP](/fr/products/managed-postgres/security), Hyperdrive se connecte depuis les [plages d'adresses IP de Cloudflare](https://www.cloudflare.com/ips/), qui doivent donc être autorisées.
</Note>

<h2 id="create-database">
  Créer la base de données
</h2>

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** :

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

```bash theme={null}
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());"
```

```text theme={null}
CREATE TABLE
```

<h2 id="create-project">
  Créer le projet Worker
</h2>

Créez un Worker TypeScript à partir du modèle « Hello World » avec `create-cloudflare`, puis installez `pg` :

```bash theme={null}
npm create cloudflare@latest -- hyperdrive-notes --type=hello-world --lang=ts --no-deploy
cd hyperdrive-notes
npm install pg
npm install -D @types/pg
```

<Tip>
  **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](#create-hyperdrive), qui ajoute le binding Hyperdrive, et à [Configurer le Worker](#configure-worker), qui active `nodejs_compat`.
</Tip>

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.

<h2 id="create-hyperdrive">
  Créer une configuration Hyperdrive
</h2>

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 :

```bash theme={null}
npx wrangler cert upload certificate-authority --ca-cert ca-certificate.pem --name managed-postgres-ca
```

```text theme={null}
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 :

```bash theme={null}
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
```

```text theme={null}
✅ 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.

<Tip>
  **Mise en cache des requêtes**

  Hyperdrive 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](https://developers.cloudflare.com/hyperdrive/concepts/query-caching/).
</Tip>

<h2 id="configure-worker">
  Configurer le Worker
</h2>

`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 :

```jsonc title="wrangler.jsonc" theme={null}
{
	"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é :

```bash theme={null}
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.

<h2 id="query">
  Interroger la base de données
</h2>

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` :

```ts title="src/index.ts" theme={null}
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.

<Note>
  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.
</Note>

<h2 id="local-development">
  Exécution en local
</h2>

`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 :

```bash theme={null}
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
```

```text theme={null}
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`.

<Warning>
  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`.
</Warning>

Dans un second terminal, créez une note :

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

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

Affichez la liste des notes :

```bash theme={null}
curl http://localhost:3108/notes
```

```json theme={null}
[{"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`.

<h2 id="deploy">
  Déploiement
</h2>

Déployez le Worker :

```bash theme={null}
npx wrangler deploy
```

```text theme={null}
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é :

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

```json theme={null}
{"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 :

```json theme={null}
[{"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"}]
```

<h2 id="verify">
  Vérifier dans la console
</h2>

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 |

<h2 id="clean-up">
  Nettoyage
</h2>

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

```bash theme={null}
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.

<h2 id="next-steps">
  Étapes suivantes
</h2>

* [Connexion](/fr/products/managed-postgres/connection) : chaînes de connexion, PgBouncer et TLS
* [Paramètres](/fr/products/managed-postgres/settings) : paramètres Postgres tels que `max_connections`
* [Répliques en lecture](/fr/products/managed-postgres/read-replicas) : faire évoluer la capacité de lecture
* [Documentation Hyperdrive](https://developers.cloudflare.com/hyperdrive/) : mise en cache des requêtes, optimisation du pool de connexions et observability