Skip to main content
Kysely est un générateur de requêtes SQL typé pour TypeScript. Dans ce guide, vous allez connecter Kysely à ClickHouse Managed Postgres via le driver pg avec une connexion TLS vérifiée, créer une table à l’aide des migrations Kysely, puis exposer depuis Node.js une petite API de gestion de tâches (to-do).

Prérequis

  • Node.js 22.18 ou version ultérieure, qui exécute directement les fichiers TypeScript sans étape de compilation. Les fichiers de ce guide utilisent l’extension .mts : Node.js les traite donc comme des modules ES, que le projet soit en CommonJS ou en modules ES.
  • 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.
  • curl, pour appeler l’API.
Ce guide a été testé avec Node.js 24.21, Kysely 0.29.6, pg 8.23.1, TypeScript 7.0.2 et PostgreSQL 18.

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. Laissez Directly sélectionné et activez Use SSL : la chaîne de connexion url se termine alors par sslmode=verify-full&sslrootcert=.... Cliquez sur Download CA certificate pour télécharger le certificat CA de votre service, nommé <service-name>-ca-certificate.pem, puis copiez la chaîne de connexion. Ce guide se connecte directement à Postgres sur le port 5432, pour deux raisons :
  • Un serveur Node.js est un processus de longue durée. Le Pool de pg maintient déjà ouvertes quelques connexions qu’il réutilise ; un pooler côté serveur n’apporte donc pas grand-chose.
  • Le Migrator de Kysely détient un verrou consultatif de niveau session (pg_advisory_lock) pendant l’exécution des migrations. Or PgBouncer fonctionne en mode de pool par transaction : l’acquisition du verrou, l’exécution des migrations et la libération du verrou peuvent donc chacune s’effectuer sur une connexion backend différente. Via PgBouncer, le verrou peut rester détenu sur une connexion du pool, et les exécutions de migrations suivantes restent alors bloquées en attendant sa libération.
Si vous exécutez par la suite de nombreuses instances de l’application ou des fonctions serverless, vous pouvez faire pointer la chaîne de connexion de l’application vers PgBouncer (port 6432, même hôte). Kysely avec pg fonctionne en mode de pool par transaction, car pg utilise par défaut des prepared statements non nommés. Continuez toutefois à exécuter les migrations sur le port 5432. Consultez Pool de connexions PgBouncer.

Configurer le projet

Créez un projet, puis installez Kysely, le driver pg et TypeScript :
Vous ajoutez Kysely à une application existante ?Ignorez mkdir kysely-todo && cd kysely-todo et npm init -y. Dans votre projet, exécutez les commandes suivantes, qui ajoutent les scripts migrate et typecheck sans toucher à votre script start, 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 de votre projet, puis renommez-le en ca-certificate.pem. Créez ensuite une base de données pour l’application :
Ajoutez la chaîne de connexion que vous avez copiée dans un fichier .env, ou dans votre fichier .env existant. Remplacez <PASSWORD> par votre mot de passe et le nom de la base de données par guide_kysely, puis attribuez la valeur ca-certificate.pem à sslrootcert :
.env
pg lit sslmode et sslrootcert dans la chaîne de connexion : avec verify-full, il vérifie que le certificat du serveur est signé par la CA de votre service et qu’il correspond au nom d’hôte. sslrootcert est résolu par rapport au répertoire de travail, c’est-à-dire la racine du projet lorsque vous utilisez npm run.
Conservez sslmode=verify-full dans l’URL. Sans sslmode, pg n’utilise pas TLS et ne vérifie pas le serveur. Ne transmettez pas en plus un objet ssl à Pool : lorsque l’URL contient sslmode, les paramètres de l’URL remplacent votre objet ssl. Si vous devez charger la CA depuis une autre source qu’un fichier, retirez sslmode et sslrootcert de l’URL et transmettez plutôt ssl: { ca } à Pool.
Ajoutez un fichier tsconfig.json afin que tsc vérifie les types des fichiers mêmes qu’exécute Node.js. Si votre application dispose déjà d’un tsconfig.json, intégrez-y ces compilerOptions ainsi que le dossier migrations :
tsconfig.json

Définir l’interface de la base de données

Kysely type chaque requête à partir d’une interface décrivant vos tables. Créez src/db.mts avec cette interface et une instance Kysely qui utilise PostgresDialect avec un Pool de pg :
src/db.mts
Generated indique les colonnes que la base de données renseigne elle-même ; elles sont donc facultatives lors de l’insertion.

Créer et exécuter une migration

Ce guide utilise le Migrator intégré à Kysely avec FileMigrationProvider, qui fait partie du paquet principal kysely. La CLI distincte kysely-ctl est facultative et encapsule ce même Migrator. Créez un fichier de migration. Kysely exécute les migrations selon l’ordre alphanumérique de leurs noms de fichiers ; préfixez donc ces noms par une date :
migrations/2026-09-30_create_todo.mts
Créez src/migrate.mts pour appliquer toutes les migrations en attente. Avec Kysely 0.29, importez Migrator et FileMigrationProvider depuis kysely/migration :
src/migrate.mts
Exécutez la migration :
Kysely enregistre les migrations appliquées dans la table kysely_migration : relancer la commande n’a donc aucun effet.
Pour vérifier que pg valide réellement le certificat, exécutez la migration sans sslrootcert. Par défaut, Node.js ne fait pas confiance à l’autorité de certification (CA) de votre service ; la connexion échoue donc :

Interroger la base de données

Créez src/server.mts, un petit serveur HTTP qui crée, lit, met à jour et supprime des tâches avec Kysely. Dans une application existante, vous pouvez utiliser les mêmes requêtes dans vos propres handlers de route :
src/server.mts
Comme chaque requête est vérifiée par rapport à l’interface Database, un nom de table ou de colonne mal orthographié, ou une insertion sans le champ obligatoire title, fait échouer la vérification des types. Vérifiez le projet :

Vérification

Démarrez le serveur :
Dans une application existante, où npm start lance votre propre application, démarrez plutôt le serveur d’exemple avec node --env-file=.env src/server.mts. Dans un autre terminal, créez, modifiez et supprimez quelques tâches :
Ouvrez http://localhost:3000/todos dans votre navigateur pour afficher la liste des tâches restantes. La réponse devrait ressembler à ceci :
Pour afficher les mêmes données dans la console, ouvrez console SQL dans la barre latérale gauche de votre service, développez guide_kysely puis le schéma public, et cliquez sur la table todo. Les tables kysely_migration et kysely_migration_lock créées par Kysely apparaissent juste à côté :

Étapes suivantes

Dernière modification le 14 octobre 2026