Bun.sql, ce qui vous évite d’avoir à installer un driver.
Dans ce guide, vous allez connecter Bun à ClickHouse Managed Postgres via une connexion TLS vérifiée, créer une table, exécuter des requêtes et une transaction, puis exposer les lignes via HTTP avec Bun.serve.
Prérequis
- Bun 1.4 ou version ultérieure. Ce guide a été testé avec Bun 1.4.2 et Postgres 18.
- 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 détaillée, consultez le guide de démarrage rapide.Obtenir vos informations de connexion
Ouvrez votre service et cliquez sur Connect dans la barre latérale gauche. Laissez l’option Directly sélectionnée et activez Use SSL. L’URL se termine alors parsslmode=verify-full&sslrootcert=.... Cliquez sur Download CA certificate pour télécharger le certificat de CA de votre instance.
Dans ce guide, la connexion s’effectue directement sur le port 5432. Une application Bun.serve est un processus de longue durée, et Bun.sql gère son propre pool de connexions : un pooler côté serveur est donc superflu. Si vous exécutez de nombreux processus Bun de courte durée, consultez Se connecter via PgBouncer.
Configurer le projet
Créez un projet :Configurer la connexion
Déplacez le certificat de CA que vous avez téléchargé dans le projet, puis renommez-le enca-certificate.pem :
<PASSWORD> et l’hôte par les valeurs affichées dans la fenêtre modale Connect :
guide_bun dans le fichier .env, en le créant s’il n’existe pas. Bun charge automatiquement .env, et l’export sql de bun lit la variable DATABASE_URL :
.env
.env : excluez-le du contrôle de version.
Ajoutez ces scripts à package.json, en les fusionnant dans le bloc scripts s’il existe déjà. Ils transmettent le certificat de CA à Bun via NODE_EXTRA_CA_CERTS :
package.json
Comment Bun vérifie le certificat du serveur
sslmode=verify-fullpermet àBun.sqlde vérifier à la fois la chaîne de certificats et le nom d’hôte.- Ne copiez pas le paramètre
sslrootcertdepuis l’URL de la console.Bun.sqlne le lit pas : il le transmet au serveur comme paramètre d’exécution, et la connexion échoue avec l’erreurunrecognized configuration parameter "sslrootcert". NODE_EXTRA_CA_CERTSdoit être défini dans l’environnement au démarrage de Bun. Bun ne le lit pas depuis.env, c’est pourquoi il figure dans les scripts.- Avec Bun 1.4.2, transmettre le certificat téléchargé via l’option
tls: { ca }deSQLprovoque l’erreurcertificate signature failure. Utilisez plutôtNODE_EXTRA_CA_CERTS.
Créer une table
Créez le fichiersetup.ts. Il affiche l’état TLS de la session et crée une table todos :
setup.ts
Interroger la base de données
Bun.sql utilise des gabarits étiquetés (tagged templates). Chaque valeur interpolée est transmise sous forme de paramètre lié : vous pouvez donc transmettre des saisies utilisateur en toute sécurité. Créez queries.ts :
queries.ts
sql.begin exécute la fonction de rappel dans une transaction. La transaction est validée lorsque la fonction de rappel se termine, et annulée si celle-ci lève une exception.
Exécutez-le :
Exposer les lignes via HTTP
Créezserver.ts avec un endpoint /todos qui liste et crée des lignes :
server.ts
Vérification
Ouvrez http://localhost:3106/todos dans votre navigateur pour afficher toutes les lignes. La réponse se présente comme suit (mise en forme pour plus de lisibilité) :Se connecter via PgBouncer
Si vous exécutez de nombreux processus Bun de courte durée, connectez-vous plutôt via le PgBouncer fourni. Sélectionnez via PgBouncer dans la fenêtre modale Connect et remplacez le port dansDATABASE_URL par 6432. Le certificat de CA et sslmode=verify-full restent inchangés.
PgBouncer fonctionne en mode de pool de connexions par transaction. Par défaut, Bun.sql utilise des prepared statements nommés ; lors de nos tests, ceux-ci ont fonctionné via PgBouncer sans aucune erreur. Si vous rencontrez des erreurs prepared statement does not exist, créez le client avec prepare: false :
prepare en tant qu’option, et non dans l’URL. Comme pour sslrootcert, un paramètre d’URL prepare=false est transmis au serveur, qui le rejette.
Étapes suivantes
- Connexion : chaînes de connexion, PgBouncer et TLS
- Paramètres : modifier les paramètres de Postgres et de PgBouncer
- Répliques en lecture : faire évoluer la capacité de lecture
- Documentation Bun SQL : l’API
Bun.sqlcomplète