Skip to main content
node-postgres (el paquete pg) es el controlador de Postgres más utilizado para Node.js. En esta guía, se conectará a ClickHouse Managed Postgres mediante un pg.Pool con verificación completa de certificados TLS, creará dos tablas, transferirá dinero entre cuentas dentro de una transacción y servirá los datos a través de un pequeño servidor node:http.

Requisitos previos

  • Node.js 20.6 o posterior (para el indicador integrado --env-file). Esta guía se ha probado con Node.js 24.21.0 y pg 8.23.1.
  • Una cuenta de ClickHouse Cloud
  • psql, para crear la base de datos

Crear un servicio de ClickHouse Managed Postgres

En la consola de ClickHouse Cloud, haga clic en New service y seleccione Postgres. La instancia estará lista en unos minutos. Consulte la guía de inicio rápido para ver el proceso paso a paso.

Obtenga los detalles de conexión

Haga clic en Conectar en la barra lateral izquierda de su servicio. Con la opción Directly seleccionada, copie la URL de conexión de la pestaña url. Deje Use SSL desactivado: la aplicación proporciona el certificado de CA en el código en lugar de en la URL (consulte Configurar el grupo de conexiones). Esta guía se conecta directamente a Postgres en el puerto 5432. Un servidor Node.js de ejecución prolongada ya mantiene su propio grupo de conexiones mediante pg.Pool, por lo que no necesita un segundo pooler delante de Postgres. Si ejecuta muchos procesos o funciones sin servidor, utilice en su lugar el PgBouncer incluido; consulte Usar PgBouncer. A continuación, descargue el certificado de CA de su instancia. Active Use SSL y haga clic en Download CA certificate, o vaya a Settings → CA Certificate → Download CA certificate. Cada instancia tiene su propio certificado.

Configurar el proyecto

Cree un proyecto e instale pg:
¿Va a añadirlo a una aplicación existente?Omita mkdir y npm init -y. En su proyecto, ejecute npm install pg y continúe con Crear la base de datos.
Los ejemplos de esta guía son módulos ES con la extensión .mjs, por lo que funcionan tanto si su package.json usa CommonJS como si usa módulos ES.

Crear la base de datos

Mueva el archivo descargado <service-name>-ca-certificate.pem al directorio del proyecto y cámbiele el nombre a ca-certificate.pem. A continuación, cree una base de datos para la aplicación:
Cree un archivo .env con la URL de conexión que copió, cambiando el nombre de la base de datos a guide_nodejs, y con la ruta al certificado:
.env
Si su contraseña contiene caracteres como @, / o #, aplíqueles codificación porcentual en la URL.

Configurar el grupo de conexiones

Cree db.mjs. Este archivo exporta un único grupo que comparte el resto de la aplicación:
db.mjs
Pasar ssl: { ca } equivale a sslmode=verify-full: pg comprueba que el certificado del servidor esté firmado por la CA de su instancia y que coincida con el nombre del host. rejectUnauthorized tiene true como valor predeterminado; no lo establezca en false.
No combine ssl con parámetros SSL en la URLSi DATABASE_URL contiene sslmode o sslrootcert, pg genera su configuración de TLS a partir de la URL e ignora el objeto ssl. Por ejemplo, una URL que termine en ?sslmode=verify-full sin sslrootcert sustituye su ca, y la conexión falla con unable to verify the first certificate. No incluya parámetros SSL en DATABASE_URL cuando pase ssl en el código.Tenga en cuenta también que:
  • Si no hay un objeto ssl ni sslmode en la URL, pg no usa TLS ni verifica el servidor.
  • pg lee PGHOST, PGUSER, PGPASSWORD y variables similares, pero no lee PGSSLROOTCERT. Por lo tanto, las variables de la pestaña env del modal Conectar no bastan por sí solas para verificar el servidor.
  • Si prefiere tenerlo todo en la URL, la URL que muestra el modal Conectar con Use SSL activado también funciona con pg; por ejemplo, ...?sslmode=verify-full&sslrootcert=ca-certificate.pem. En ese caso, elimine la opción ssl y tenga en cuenta que sslrootcert se resuelve de forma relativa al directorio desde el que se inicia Node.js.

Crear el esquema

Cree setup.mjs. Este archivo crea las tablas, inserta dos cuentas mediante consultas parametrizadas y luego las lee:
setup.mjs
Pase siempre los valores como parámetros ($1, $2, …) en lugar de concatenarlos en la cadena SQL. pg los envía por separado del texto de la consulta, lo que evita la inyección de SQL. Los arrays de JavaScript se corresponden con arrays de Postgres, como en la consulta ANY($1). Ejecútelo:
pg devuelve los valores numeric (y bigint) como cadenas para no perder precisión. Si necesita números, conviértalos explícitamente.

Ejecutar consultas en una transacción

Una transacción debe ejecutarse en una única conexión, por lo que debe obtener un Client con pool.connect y liberarlo siempre. Cree transfer.mjs:
transfer.mjs
No utilice pool.query para las sentencias dentro de una transacción: cada llamada a pool.query puede ejecutarse en una conexión distinta.

Servir los datos a través de HTTP

Cree server.mjs. Este archivo sirve las cuentas y las transferencias en formato JSON en el puerto 3107, acepta nuevas transferencias y se detiene de forma ordenada al recibir SIGINT (Ctrl+C) o SIGTERM:
server.mjs
Llame a pool.end una sola vez, cuando el proceso finalice, y no después de cada solicitud. Espera a que se liberen los Clients que estén en uso y, a continuación, cierra todas las conexiones.

Verificación

Inicie el servidor:
En una segunda terminal, realice una transferencia y, a continuación, intente otra que dejaría una cuenta en descubierto y otra a una cuenta que no existe:
La tercera transferencia ya había realizado el cargo en la cuenta de alice cuando falló, pero el ROLLBACK lo deshizo. Abra http://localhost:3107/accounts en su navegador para ver los saldos. La respuesta tiene un aspecto similar a este:
Para confirmar que la conexión utiliza TLS verificado, ejecute una consulta sobre pg_stat_ssl:
Si hace que DATABASE_CA_CERT apunte a cualquier otro certificado, la conexión falla con unable to verify the first certificate, lo que demuestra que el certificado del servidor se verifica realmente. Por último, detenga el servidor con Ctrl+C. Se mostrará SIGINT received, shutting down y, a continuación, Pool closed. También puede consultar los datos en la consola. Abra SQL console, despliegue la base de datos guide_nodejs y abra la tabla accounts:

Usar PgBouncer

Para conectarse a través del PgBouncer incluido, seleccione via PgBouncer en el modal Conectar y use el puerto 6432 en DATABASE_URL. No es necesario modificar el código; el mismo certificado de CA sigue siendo válido. PgBouncer se ejecuta en modo de agrupación de conexiones por transacción, por lo que cada transacción puede ejecutarse en una conexión de Postgres distinta. Con pg:
  • Las consultas parametrizadas, las sentencias preparadas con nombre (pool.query({ name, text, values })) y las transacciones que usan pool.connect funcionan tal como se muestra en esta guía.
  • Las sentencias PREPARE y EXECUTE a nivel de SQL, así como la configuración de sesión establecida con SET, no se mantienen entre transacciones. En su lugar, use SET LOCAL dentro de una transacción.
  • pg_stat_ssl refleja la conexión entre PgBouncer y Postgres, por lo que la consulta de comprobación de TLS anterior devuelve ssl: false. Aun así, la conexión de su aplicación con PgBouncer se sigue verificando: con un certificado de CA incorrecto, la conexión falla igualmente.

Próximos pasos