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 statementCREATE DATABASEdans la console SQL.curl, pour appeler l’API.
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 parsslmode=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
Pooldepgmaintient déjà ouvertes quelques connexions qu’il réutilise ; un pooler côté serveur n’apporte donc pas grand-chose. - Le
Migratorde 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.
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 driverpg et TypeScript :
Configurer la connexion
Déplacez le certificat CA que vous avez téléchargé dans le répertoire de votre projet, puis renommez-le enca-certificate.pem. Créez ensuite une base de données pour l’application :
.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.
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éezsrc/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 leMigrator 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
src/migrate.mts pour appliquer toutes les migrations en attente. Avec Kysely 0.29, importez Migrator et FileMigrationProvider depuis kysely/migration :
src/migrate.mts
kysely_migration : relancer la commande n’a donc aucun effet.
Interroger la base de données
Créezsrc/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
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 :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 :
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
- Connexion : chaînes de connexion, PgBouncer et TLS.
- Paramètres : ajustez les paramètres de PostgreSQL et de PgBouncer, comme
max_connections. - Réplicas en lecture : faites évoluer les charges de travail intensives en lecture.
- Documentation de Kysely : jointures, transactions et génération de types.