Skip to main content
Kysely es un generador de consultas SQL con tipado seguro para TypeScript. En esta guía, conectará Kysely a ClickHouse Managed Postgres mediante el controlador pg con verificación TLS, creará una tabla con migraciones de Kysely y expondrá una pequeña API de lista de tareas desde Node.js.

Requisitos previos

  • Node.js 22.18 o posterior, que ejecuta archivos TypeScript directamente sin necesidad de un paso de build. Los archivos de esta guía usan la extensión .mts, por lo que Node.js los trata como módulos ES tanto en proyectos CommonJS como en proyectos de módulos ES.
  • Una cuenta de ClickHouse Cloud.
  • psql, para crear la base de datos. También puede ejecutar la sentencia CREATE DATABASE en la consola SQL.
  • curl, para llamar a la API.
Esta guía se probó con Node.js 24.21, Kysely 0.29.6, pg 8.23.1, TypeScript 7.0.2 y PostgreSQL 18.

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.

Obtén los detalles de conexión

Haz clic en Connect en la barra lateral izquierda de tu servicio. Deja seleccionada la opción Directly y activa Use SSL: la cadena de conexión url terminará ahora en sslmode=verify-full&sslrootcert=.... Haz clic en Download CA certificate para descargar el certificado de CA de tu servicio, llamado <service-name>-ca-certificate.pem, y copia la cadena de conexión. En esta guía, la conexión a Postgres se realiza directamente en el puerto 5432, por dos motivos:
  • Un servidor Node.js es un proceso de larga duración. El Pool de pg ya mantiene abiertas unas pocas conexiones y las reutiliza, así que un pooler del lado del servidor aporta poco.
  • El Migrator de Kysely mantiene un bloqueo consultivo a nivel de sesión (pg_advisory_lock) mientras ejecuta las migraciones. PgBouncer funciona en modo de pooling por transacción, por lo que la adquisición del bloqueo, la ejecución de las migraciones y la liberación del bloqueo pueden acabar cada una en una conexión de backend distinta. A través de PgBouncer, el bloqueo puede quedar retenido en una conexión del grupo, y las ejecuciones posteriores de migraciones se quedan bloqueadas a la espera de que se libere.
Si más adelante ejecutas muchas instancias de la aplicación o funciones sin servidor, puedes hacer que la cadena de conexión de la aplicación apunte a PgBouncer (puerto 6432, mismo host). Kysely con pg funciona en modo de pooling por transacción porque pg utiliza de forma predeterminada sentencias preparadas sin nombre. Sigue ejecutando las migraciones contra el puerto 5432. Consulta Pooling de conexiones con PgBouncer.

Configurar el proyecto

Cree un proyecto e instale Kysely, el controlador pg y TypeScript:
¿Lo va a añadir a una aplicación existente?Omita mkdir kysely-todo && cd kysely-todo y npm init -y. En su proyecto, ejecute los siguientes comandos, que añaden los scripts migrate y typecheck sin modificar su script start, y después continúe con Configurar la conexión.

Configurar la conexión

Mueva el certificado de CA que descargó al directorio de su proyecto y cámbiele el nombre a ca-certificate.pem. A continuación, cree una base de datos para la aplicación:
Añade la cadena de conexión que copiaste a un archivo .env nuevo o al .env que ya tengas. Sustituye <PASSWORD> por tu contraseña y el nombre de la base de datos por guide_kysely, y asigna a sslrootcert el valor ca-certificate.pem:
.env
pg lee sslmode y sslrootcert de la cadena de conexión: con verify-full, comprueba que el certificado del servidor esté firmado por la CA de su servicio y que coincida con el nombre del host. sslrootcert se resuelve de forma relativa al directorio de trabajo, que es la raíz del proyecto cuando se usa npm run.
Mantenga sslmode=verify-full en la URL. Sin sslmode, pg no usa TLS ni verifica el servidor. No pase además un objeto ssl a Pool: cuando la URL contiene sslmode, la configuración de la URL reemplaza su objeto ssl. Si necesita cargar la CA desde un origen que no sea un archivo, elimine sslmode y sslrootcert de la URL y, en su lugar, pase ssl: { ca } a Pool.
Añada un tsconfig.json para que tsc compruebe los tipos de los mismos archivos que ejecuta Node.js. Si su aplicación ya tiene un tsconfig.json, incorpore en él estas compilerOptions y la carpeta migrations:
tsconfig.json

Definir la interfaz de la base de datos

Kysely asigna tipos a cada consulta a partir de una interfaz que describe sus tablas. Cree src/db.mts con la interfaz y una instancia de Kysely que utilice PostgresDialect con un Pool de pg:
src/db.mts
Generated marca las columnas que rellena la propia base de datos, por lo que son opcionales al insertar.

Crear y ejecutar una migración

Esta guía utiliza el Migrator integrado de Kysely con FileMigrationProvider, que forma parte del paquete principal kysely. La CLI independiente kysely-ctl es opcional y envuelve el mismo Migrator. Cree un archivo de migración. Kysely ejecuta las migraciones en orden alfanumérico según el nombre de archivo, así que añada una fecha como prefijo:
migrations/2026-09-30_create_todo.mts
Cree src/migrate.mts para aplicar todas las migraciones pendientes. En Kysely 0.29, importe Migrator y FileMigrationProvider desde kysely/migration:
src/migrate.mts
Ejecute la migración:
Kysely registra las migraciones aplicadas en la tabla kysely_migration, por lo que volver a ejecutar el comando no tiene ningún efecto.
Para comprobar que pg realmente verifica el certificado, ejecute la migración sin sslrootcert. Node.js no confía de forma predeterminada en la CA de su servicio, por lo que la conexión falla:

Consultar la base de datos

Cree src/server.mts, un pequeño servidor HTTP que crea, lee, actualiza y elimina tareas pendientes con Kysely. En una aplicación existente, puede usar las mismas consultas en sus propios handlers de ruta:
src/server.mts
Como cada consulta se valida con la interfaz Database, un nombre de tabla o de columna mal escrito, o una inserción sin el campo obligatorio title, provoca un error en la comprobación de tipos. Compruebe el proyecto:

Verificación

Inicie el servidor:
En una aplicación existente, donde npm start ejecuta su propia aplicación, inicie en su lugar el servidor de ejemplo con node --env-file=.env src/server.mts. En otra terminal, cree, actualice y elimine algunas tareas pendientes:
Abra http://localhost:3000/todos en su navegador para ver la lista de tareas pendientes. La respuesta será similar a esta:
Para ver los mismos datos en la consola, abra consola SQL en la barra lateral izquierda de su servicio, expanda guide_kysely y el esquema public, y haga clic en la tabla todo. Junto a ella aparecen las tablas kysely_migration y kysely_migration_lock que creó Kysely:

Próximos pasos

Última modificación el 14 de octubre de 2026