Skip to main content
Prisma ORM est un ORM TypeScript qui propose un schéma déclaratif, un outil de migration (Prisma Migrate) et un client généré à typage sûr. Dans ce guide, vous allez connecter Prisma à ClickHouse Managed Postgres, créer une table au moyen d’une migration, puis l’interroger depuis un script et un petit endpoint HTTP. Ce guide utilise Prisma ORM 7 (testé avec la version 7.10.0), la version stable actuelle.

Prérequis

  • Node.js 20.19, 22.12, ou 24 et versions ultérieures
  • Un service ClickHouse Managed Postgres
  • psql, pour créer la base de données. Vous pouvez également exécuter le statement CREATE DATABASE dans la console SQL.
  • Sous macOS : Docker, pour exécuter Prisma Migrate (voir Exécuter la migration)

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 les informations de connexion

Cliquez sur Connect dans la barre latérale gauche de votre service. La fenêtre modale affiche votre nom d’utilisateur, votre mot de passe, le serveur et le port, ainsi que des chaînes de connexion prêtes à l’emploi. Ce guide utilise deux connexions, car Prisma comporte deux composants qui communiquent avec la base de données :
  • Votre application (Prisma Client) se connecte via PgBouncer sur le port 6432. PgBouncer mutualise les connexions, ce qui permet à de nombreux processus applicatifs ou instances serverless de partager un petit nombre de backends Postgres.
  • La CLI Prisma (Prisma Migrate) se connecte directement sur le port 5432. Pendant son exécution, Prisma Migrate pose un verrou consultatif (advisory lock) au niveau de la session. En mode pool de connexions par transaction de PgBouncer, ce verrou peut rester actif sur un backend mutualisé qui sert ensuite d’autres clients, et les migrations suivantes se retrouvent alors bloquées.
En haut de la fenêtre modale, basculez entre Directly et via PgBouncer pour afficher le port correspondant. Le serveur et les identifiants sont identiques pour les deux connexions ; seul le port change. Lorsque via PgBouncer est sélectionné, cliquez sur Download CA certificate. Lorsque Directly est sélectionné, activez d’abord Use SSL pour faire apparaître le bouton. Le fichier est nommé <service-name>-ca-certificate.pem. Vous le trouverez également sous Settings → CA Certificate. Ce certificat est propre à votre instance ; il vous permet de vous connecter avec sslmode=verify-full, qui vérifie que vous communiquez bien avec votre propre serveur.

Configurer le projet

Créez un projet TypeScript et installez la CLI Prisma, Prisma Client, l’adaptateur de driver node-postgres ainsi que dotenv :
Installez explicitement prisma@7 et @prisma/client@7. Au moment de la rédaction de ce guide, le tag npm latest de prisma pointe vers une version candidate (RC) de Prisma 8, dont la configuration diffère de celle décrite ici.
Créez un fichier tsconfig.json :
Vous l’intégrez à une application existante ?Ignorez mkdir, npm init et le fichier tsconfig.json. Dans votre projet, exécutez npm install tsx @types/pg prisma@7 --save-dev et npm install @prisma/client@7 @prisma/adapter-pg pg dotenv, puis passez à l’étape Initialiser Prisma.

Initialiser Prisma

1

Exécuter prisma init

Cette commande crée prisma/schema.prisma ainsi que le fichier de configuration Prisma prisma7.config.ts, ajoute un caractère de substitution pour DATABASE_URL dans .env et le client généré dans .gitignore (en créant ces fichiers si nécessaire), puis ajoute des skills Prisma destinés aux agents de code IA. À partir de la version 7.10, Prisma nomme le fichier de configuration prisma7.config.ts afin d’éviter tout conflit avec le format de Prisma 8.
2

Ajouter le certificat de CA

Déplacez le certificat de CA que vous avez téléchargé à la racine du projet et renommez-le en ca-certificate.pem :
Les paths relatifs des certificats sont résolus à partir du répertoire depuis lequel vous exécutez les commandes : exécutez donc toutes les commandes de ce guide depuis la racine du projet.

Configurer la connexion

1

Créer une base de données

Créez une base de données pour l’application. Remplacez <PASSWORD> et l’hôte par les valeurs indiquées dans la fenêtre modale Connect :
2

Définir les URL de connexion

Dans .env, remplacez le caractère de substitution de DATABASE_URL ajouté par prisma init par ces deux URL de connexion, qui pointent toutes deux vers la base de données guide_prisma. Utilisez le mot de passe indiqué dans la fenêtre modale Connect :
Les deux URL utilisent des paramètres TLS différents, car elles sont lues par des drivers différents :
  • DATABASE_URL est lue par node-postgres via @prisma/adapter-pg. Elle prend en charge les paramètres standard sslmode=verify-full&sslrootcert=..., identiques à ceux affichés dans la fenêtre modale Connect.
  • DIRECT_URL est lue par le moteur de schéma de la CLI Prisma, qui utilise ses propres paramètres : sslcert indique le path du certificat de CA, et sslaccept=strict active la vérification du certificat et du nom d’hôte.
N’utilisez pas sslmode=verify-full&sslrootcert=... dans l’URL destinée à la CLI Prisma. Le moteur de schéma ignore sslrootcert et, sans sslaccept=strict, ne vérifie absolument pas le certificat du serveur : la connexion est alors chiffrée, mais non authentifiée.
3

Faire pointer la CLI Prisma vers la connexion directe

Remplacez le contenu de prisma7.config.ts :
Dans Prisma 7, l’URL définie dans le fichier de configuration n’est utilisée que par la CLI. Prisma Client obtient sa connexion via l’adaptateur de driver, que vous configurerez dans Interroger la base de données.

Définir le schéma et exécuter la migration

1

Ajouter un modèle

Ajoutez un modèle Todo à la fin de prisma/schema.prisma :
2

Exécuter la migration

Sous Linux, exécutez directement Prisma Migrate :
Sous macOS, exécutez la même commande dans un conteneur Linux :
ClickHouse Managed Postgres n’accepte que TLS 1.3. Sous macOS, le moteur de schéma de la CLI Prisma s’appuie sur la bibliothèque TLS du système, qui ne parvient pas à établir la connexion avec ces paramètres. La commande échoue alors avec l’erreur P1011: Error opening a TLS connection: One or more parameters passed to a function were not valid, ou avec bad protocol version si vous supprimez sslcert (prisma/orm#29600). Seules les commandes de la CLI qui se connectent à la base de données, comme prisma migrate et prisma db pull, sont concernées. Prisma Client n’est pas affecté, car il se connecte via node-postgres. Pour contourner le problème, exécutez la CLI dans un conteneur Linux ou dans votre pipeline d’intégration continue sous Linux.
Prisma crée la migration SQL dans prisma/migrations/, puis l’applique :
3

Générer Prisma Client

Le client est généré dans generated/prisma. Cette commande ne se connecte pas à la base de données : vous pouvez donc l’exécuter sur n’importe quelle plateforme.

Interroger la base de données

1

Créer le Prisma Client

Créez lib/prisma.ts. L’adaptateur PrismaPg se connecte via PgBouncer à l’aide de DATABASE_URL :
Aucun paramètre PgBouncer requis@prisma/adapter-pg envoie chaque requête sous forme de prepared statement anonyme et n’exécute jamais DEALLOCATE, ce qui le rend compatible avec le mode de pool de connexions par transaction de PgBouncer. Il gère sans erreur des centaines de requêtes distinctes exécutées simultanément sur les backends du pool. Le paramètre d’URL pgbouncer=true des anciennes versions de Prisma est inutile et n’a aucun effet avec l’adaptateur de driver.
2

Exécuter des requêtes CRUD

Créez script.ts :
Exécutez-le :
3

Exposer les données via HTTP

Créez server.ts, un serveur HTTP minimal qui crée des todos via POST /todos et les renvoie pour toute requête GET :
Démarrez le serveur :
Dans un deuxième terminal, ajoutez deux todos :
Ouvrez http://localhost:3000/todos dans votre navigateur pour les afficher. La réponse se présente ainsi :

Vérifier dans la console SQL

Dans la console ClickHouse Cloud, ouvrez la console SQL de votre service, développez votre base de données et le schéma public, puis sélectionnez la table Todo. Vous y verrez également la table _prisma_migrations, dans laquelle Prisma Migrate consigne les migrations appliquées. La table Todo contient les deux lignes que vous avez ajoutées via l’endpoint HTTP :

Dépannage

Étapes suivantes

Dernière modification le 14 octobre 2026