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 statementCREATE DATABASEdans 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.
<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 quedotenv :
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.tsconfig.json :
Initialiser Prisma
1
Exécuter prisma init
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 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.
ca-certificate.pem :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 Les deux URL utilisent des paramètres TLS différents, car elles sont lues par des drivers différents :
.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 :DATABASE_URLest lue par node-postgres via@prisma/adapter-pg. Elle prend en charge les paramètres standardsslmode=verify-full&sslrootcert=..., identiques à ceux affichés dans la fenêtre modale Connect.DIRECT_URLest lue par le moteur de schéma de la CLI Prisma, qui utilise ses propres paramètres :sslcertindique le path du certificat de CA, etsslaccept=strictactive la vérification du certificat et du nom d’hôte.
3
Faire pointer la CLI Prisma vers la connexion directe
Remplacez le contenu de 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.
prisma7.config.ts :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 :Prisma crée la migration SQL dans
prisma/migrations/, puis l’applique :3
Générer Prisma Client
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 :2
Exécuter des requêtes CRUD
Créez Exécutez-le :
script.ts :3
Exposer les données via HTTP
Créez 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 :
server.ts, un serveur HTTP minimal qui crée des todos via POST /todos et les renvoie pour toute requête GET :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émapublic, 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
- Connexion : chaînes de connexion, PgBouncer et TLS
- Paramètres : ajuster les paramètres de Postgres et de PgBouncer
- Répliques en lecture : faire évoluer les charges de travail à forte intensité de lecture
- Développement local : développer avec une instance Postgres locale dans Docker
- Prisma Migrate en production : utiliser
prisma migrate deploydans votre pipeline d’intégration continue