pg) est le driver Postgres le plus utilisé pour Node.js. Dans ce guide, vous allez vous connecter à ClickHouse Managed Postgres via un pg.Pool avec une vérification complète du certificat TLS, créer deux tables, transférer de l’argent d’un compte à l’autre au sein d’une transaction, puis exposer les données à l’aide d’un petit serveur node:http.
Prérequis
- Node.js 20.6 ou version ultérieure (pour l’indicateur intégré
--env-file). Ce guide a été testé avec Node.js 24.21.0 etpg8.23.1. - Un compte ClickHouse Cloud
psql, pour créer la base de données
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 les informations de connexion
Cliquez sur Connect dans la barre latérale gauche de votre service. Avec l’option Directly sélectionnée, copiez l’URL de connexion depuis l’onglet url. Laissez Use SSL désactivé : l’application fournit le certificat CA dans le code plutôt que dans l’URL (voir Configurer le pool de connexions). Ce guide se connecte directement à Postgres sur le port5432. Un serveur Node.js à exécution prolongée gère déjà son propre pool de connexions via pg.Pool ; il n’a donc pas besoin d’un second pooler en amont de Postgres. Si vous exécutez de nombreux processus ou des fonctions serverless, utilisez plutôt le PgBouncer intégré (voir Utiliser PgBouncer).
Téléchargez ensuite le certificat CA de votre instance. Activez Use SSL et cliquez sur Download CA certificate, ou accédez à Settings → CA Certificate → Download CA certificate. Ce certificat est propre à votre instance.
Configurer le projet
Créez un projet et installezpg :
.mjs : ils fonctionnent donc que votre package.json utilise CommonJS ou les modules ES.
Créer la base de données
Déplacez le fichier<service-name>-ca-certificate.pem téléchargé dans le répertoire du projet, puis renommez-le en ca-certificate.pem. Créez ensuite une base de données pour l’application :
.env contenant l’URL de connexion que vous avez copiée, dans laquelle le nom de la base de données est remplacé par guide_nodejs, ainsi que le chemin d’accès au certificat :
.env
@, / ou #, appliquez-leur l’encodage-pourcent dans l’URL.
Configurer le pool de connexions
Créezdb.mjs. Ce fichier exporte un pool unique, partagé par le reste de l’application :
db.mjs
ssl: { ca } équivaut à sslmode=verify-full : pg vérifie que le certificat du serveur est signé par la CA de votre instance et qu’il correspond au nom d’hôte. rejectUnauthorized vaut true par défaut ; ne le définissez pas sur false.
Créer le schéma
Créezsetup.mjs. Ce script crée les tables, insère deux comptes à l’aide de requêtes paramétrées, puis les relit :
setup.mjs
$1, $2, …) plutôt que de les concaténer dans la chaîne SQL. pg les envoie séparément du texte de la requête, ce qui protège contre les injections SQL. Les tableaux JavaScript sont convertis en tableaux Postgres, comme dans la requête ANY($1).
Exécutez-le :
pg renvoie les valeurs numeric (et bigint) sous forme de chaînes de caractères afin d’éviter toute perte de précision. Convertissez-les explicitement si vous avez besoin de nombres.
Exécuter des requêtes dans une transaction
Une transaction doit s’exécuter sur une seule connexion : récupérez donc un client avecpool.connect, et veillez à toujours le libérer. Créez transfer.mjs :
transfer.mjs
pool.query pour les statements d’une transaction : chaque appel à pool.query peut s’exécuter sur une connexion différente.
Exposer les données via HTTP
Créezserver.mjs. Ce fichier expose les comptes et les transferts au format JSON sur le port 3107, accepte de nouveaux transferts et s’arrête proprement à la réception de SIGINT (Ctrl+C) ou de SIGTERM :
server.mjs
pool.end une seule fois, à l’arrêt du processus, et non après chaque requête. Cette méthode attend que les clients empruntés soient libérés, puis ferme toutes les connexions.
Vérification
Démarrez le serveur :alice lorsqu’il a échoué, mais le ROLLBACK a annulé ce débit. Ouvrez http://localhost:3107/accounts dans votre navigateur pour consulter les soldes. La réponse se présente comme suit :
pg_stat_ssl :
DATABASE_CA_CERT vers un autre certificat, la connexion échoue avec l’erreur unable to verify the first certificate, ce qui prouve que le certificat du serveur est bien vérifié.
Enfin, arrêtez le serveur avec Ctrl+C. Il affiche SIGINT received, shutting down, puis Pool closed.
Vous pouvez également consulter les données dans la console. Ouvrez la console SQL, développez la base de données guide_nodejs, puis ouvrez la table accounts :
Utiliser PgBouncer
Pour vous connecter via le PgBouncer intégré, sélectionnez via PgBouncer dans la fenêtre modale Connect et utilisez le port6432 dans DATABASE_URL. Aucune modification du code n’est nécessaire, et le même certificat CA reste valable.
PgBouncer fonctionne en mode de pool de connexions par transaction : chaque transaction peut donc s’exécuter sur une connexion Postgres différente. Avec pg :
- Les requêtes paramétrées, les prepared statements nommés (
pool.query({ name, text, values })) et les transactions qui utilisentpool.connectfonctionnent comme indiqué dans ce guide. - Les commandes SQL
PREPAREetEXECUTE, ainsi que les paramètres de session définis avecSET, ne sont pas conservés d’une transaction à l’autre. Utilisez plutôtSET LOCALà l’intérieur d’une transaction. pg_stat_ssldécrit la connexion entre PgBouncer et Postgres ; la requête de vérification TLS ci-dessus renvoie doncssl: false. La connexion de votre application à PgBouncer reste néanmoins vérifiée : un certificat CA incorrect provoque le même échec.
Étapes suivantes
- Connexion : chaînes de connexion, PgBouncer et TLS
- Paramètres : modifier des paramètres tels que
max_connections - Répliques en lecture : acheminer les requêtes en lecture seule vers une réplique
- Haute disponibilité : instances de secours (standbys) et basculement (failover)