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 ypg8.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 puerto5432. 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 instalepg:
.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:
.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
@, / o #, aplíqueles codificación porcentual en la URL.
Configurar el grupo de conexiones
Creedb.mjs. Este archivo exporta un único grupo que comparte el resto de la aplicación:
db.mjs
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.
Crear el esquema
Creesetup.mjs. Este archivo crea las tablas, inserta dos cuentas mediante consultas parametrizadas y luego las lee:
setup.mjs
$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 conpool.connect y liberarlo siempre. Cree transfer.mjs:
transfer.mjs
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
Creeserver.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
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: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:
pg_stat_ssl:
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 puerto6432 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 usanpool.connectfuncionan tal como se muestra en esta guía. - Las sentencias
PREPAREyEXECUTEa nivel de SQL, así como la configuración de sesión establecida conSET, no se mantienen entre transacciones. En su lugar, useSET LOCALdentro de una transacción. pg_stat_sslrefleja la conexión entre PgBouncer y Postgres, por lo que la consulta de comprobación de TLS anterior devuelvessl: 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
- Conexión: cadenas de conexión, PgBouncer y TLS
- Configuración: modifique parámetros como
max_connections - Réplicas de lectura: envíe consultas de solo lectura a una réplica
- Alta disponibilidad: instancias standby y conmutación por error (failover)