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 statementCREATE DATABASEdans 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) pourdrizzle-kit. Les migrations exécutent du DDL, peuvent durer longtemps et dépendre de l’état de session, par exempleSET 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.
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 drivernode-postgres (pg) ainsi que drizzle-kit :
Configurer la connexion
Déplacez le certificat CA que vous avez téléchargé dans le répertoire du projet et renommez-le enca-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 :
.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 fichiersrc/db/schema.ts :
src/db/schema.ts
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 :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 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éezsrc/db/index.ts. Ce fichier instancie le client Drizzle sur un pool node-postgres qui passe par la connexion PgBouncer :
src/db/index.ts
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 :PATCH renvoie la ligne mise à jour :
http://localhost:3101/todos dans votre navigateur pour afficher la liste des tâches restantes. La réponse se présente comme suit :
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
- Connexion : chaînes de connexion, PgBouncer et TLS
- Paramètres : paramètres de Postgres et de PgBouncer, tels que
max_connections - Répliques en lecture : répartissez la charge de lecture avec
withReplicasde Drizzle - Sécurité : listes d’accès IP et réseau privé