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 sentenciaCREATE DATABASEen la consola SQL.curl, para llamar a la API.
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 ensslmode=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
Pooldepgya mantiene abiertas unas pocas conexiones y las reutiliza, así que un pooler del lado del servidor aporta poco. - El
Migratorde 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.
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 controladorpg y TypeScript:
Configurar la conexión
Mueva el certificado de CA que descargó al directorio de su proyecto y cámbiele el nombre aca-certificate.pem. A continuación, cree una base de datos para la aplicación:
.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.
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. Creesrc/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 elMigrator 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
src/migrate.mts para aplicar todas las migraciones pendientes. En Kysely 0.29, importe Migrator y FileMigrationProvider desde kysely/migration:
src/migrate.mts
kysely_migration, por lo que volver a ejecutar el comando no tiene ningún efecto.
Consultar la base de datos
Creesrc/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
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: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:
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
- Conexión: cadenas de conexión, PgBouncer y TLS.
- Configuración: ajuste los parámetros de PostgreSQL y PgBouncer, como
max_connections. - Réplicas de lectura: escale workloads con un uso intensivo de lecturas.
- Documentación de Kysely: joins, transacciones y generación de tipos.