Skip to main content
Drizzle ORM est un ORM TypeScript doté d’un query builder à la syntaxe proche du SQL, et drizzle-kit est la CLI qui l’accompagne pour générer et exécuter des migrations. Dans ce guide, vous définissez une table todos en TypeScript, vous la créez au moyen d’une migration drizzle-kit, puis vous servez des requêtes de création, de lecture, de mise à jour et de suppression depuis un petit serveur HTTP Node.js. Toutes les connexions utilisent TLS avec une vérification complète des certificats.

Prérequis

  • Node.js 20 ou version ultérieure
  • Un compte ClickHouse Cloud
  • psql, pour créer la base de données. Vous pouvez également exécuter le statement CREATE DATABASE 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. La fenêtre modale affiche votre nom d’utilisateur, votre mot de passe, le serveur et le port, ainsi qu’un bouton bascule Directly / via PgBouncer. Ce guide utilise deux chaînes de connexion :
  • Directe (port 5432) pour drizzle-kit. Les migrations exécutent du DDL, peuvent durer longtemps et dépendre de l’état de session, par exemple SET lock_timeout ; elles doivent donc communiquer directement avec Postgres.
  • PgBouncer (port 6432) pour l’application. Le PgBouncer intégré fonctionne en mode de pool de connexions par transaction et permet à de nombreuses instances de l’application, y compris des fonctions serverless, de se partager un petit nombre de connexions Postgres.
Si vous exécutez un seul serveur Node.js de longue durée, node-postgres gère déjà son propre pool de connexions ; vous pouvez donc aussi faire pointer l’application vers la connexion directe. Utilisez la connexion PgBouncer lorsque vous répartissez la charge sur de nombreux processus ou que vous déployez sur des plateformes serverless.
Une fois Directly sélectionné, activez Use SSL. L’URL de connexion de l’onglet url se termine alors par sslmode=verify-full&sslrootcert=<service-name>-ca-certificate.pem, et le port est 5432. Sélectionnez via PgBouncer pour afficher les informations de connexion via le pool : le port passe à 6432, et l’URL inclut toujours sslmode=verify-full. Dans la fenêtre modale, cliquez sur Download CA certificate. Vous pouvez également le télécharger depuis Settings → CA Certificate. Ce certificat est propre à votre instance, ce qui permet au driver de vérifier qu’il communique bien avec votre serveur.

Configurer le projet

Créez un projet et installez Drizzle ORM, le driver node-postgres (pg) ainsi que drizzle-kit :
Vous ajoutez Drizzle à une application existante ?Ignorez les commandes mkdir, npm init et npm pkg set type=module. Dans votre projet, exécutez npm install drizzle-orm pg dotenv et npm install -D drizzle-kit tsx @types/pg, puis passez directement à la section Configurer la connexion.

Configurer la connexion

Déplacez le certificat CA que vous avez téléchargé dans le répertoire du projet et renommez-le en ca-certificate.pem. 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 :
Ajoutez les deux chaînes de connexion à un fichier .env à la racine du projet, ou à votre fichier .env existant. Elles ne diffèrent que par le port et pointent toutes deux vers la base de données guide_drizzle :
.env
node-postgres lit sslmode=verify-full et sslrootcert depuis l’URL. Il charge le fichier de l’autorité de certification (CA) et vérifie à la fois la chaîne de certificats et le nom d’hôte : vous n’avez donc besoin d’aucun code TLS supplémentaire. Le path sslrootcert est résolu par rapport au répertoire depuis lequel vous exécutez les commandes. Ne versionnez pas le fichier .env : excluez-le du contrôle de version.
Si le fichier de la CA est manquant ou incorrect, la connexion échoue avec l’erreur unable to verify the first certificate. Si le nom d’hôte ne correspond pas au certificat, elle échoue avec l’erreur ERR_TLS_CERT_ALTNAME_INVALID. Si votre mot de passe contient des caractères spéciaux tels que @, / ou #, encodez-les au format URL.

Définir le schéma

Créez le fichier src/db/schema.ts :
src/db/schema.ts
Créez drizzle.config.ts à la racine du projet. Ce fichier indique à drizzle-kit où trouver le schéma et quelle connexion directe utiliser :
drizzle.config.ts

Exécuter les migrations

Générez une migration SQL à partir du schéma :
Le fichier drizzle/0000_init.sql généré contient le statement CREATE TABLE. Relisez-le, puis commitez le dossier drizzle avec votre code. Appliquez-le ensuite :
drizzle-kit migrate enregistre les migrations appliquées dans la table drizzle.__drizzle_migrations et n’exécute que les nouvelles lors des appels suivants. Chaque fois que vous modifiez schema.ts, exécutez generate, puis à nouveau migrate.
drizzle-kit migrate se termine avec le statut 1, sans aucun message d’erreur, lorsqu’il ne parvient pas à se connecter, par exemple si le path sslrootcert ou le mot de passe est incorrect. Dans ce cas, testez d’abord DIRECT_DATABASE_URL avec psql.
drizzle-kit push applique les modifications de schéma sans passer par des fichiers de migration. C’est pratique pour le prototypage, mais en production, generate et migrate vous offrent des fichiers SQL que vous pouvez relire, ainsi qu’un historique.

Interroger la base de données

Créez src/db/index.ts. Ce fichier instancie le client Drizzle sur un pool node-postgres qui passe par la connexion PgBouncer :
src/db/index.ts
Créez src/server.ts, un petit serveur HTTP qui exécute une requête Drizzle par route. Dans une application existante, vous pouvez à la place appeler ces mêmes requêtes db depuis vos propres handlers de route :
src/server.ts
Aucun paramètre de driver n’est nécessaire pour PgBouncer. Par défaut, les requêtes de Drizzle utilisent des statements non nommés, et le PgBouncer intégré prend également en charge les prepared statements nommés, comme ceux créés avec la méthode .prepare de Drizzle, en mode pool de connexions par transaction. Les fonctionnalités propres à la session, comme LISTEN et les verrous consultatifs de session, ne fonctionnent pas via PgBouncer. Consultez la FAQ.

Exécuter et vérifier

Démarrez le serveur :
Dans un second terminal, créez deux tâches, marquez la première comme terminée et supprimez la seconde :
La requête PATCH renvoie la ligne mise à jour :
Ouvrez http://localhost:3101/todos dans votre navigateur pour afficher la liste des tâches restantes. La réponse se présente comme suit :
Pour afficher les données dans la console, ouvrez console SQL dans la barre latérale gauche de votre service, développez guide_drizzle puis public, et cliquez sur la table todos. Le schéma drizzle héberge la table d’historique des migrations. La table todos contient la ligne restante :

Étapes suivantes