Kysely para TypeScript: guía completa del type-safe SQL query builder

1. ¿Qué es y para qué sirve?

Kysely (se pronuncia "ki-se-li") es un moderno y type-safe SQL query builder para TypeScript y Node.js que te permite escribir consultas SQL con soporte completo de tipos en todas las etapas: desde la construcción de la consulta hasta la obtención del resultado. A diferencia de los ORM tradicionales (Object-Relational Mapping) como TypeORM o Prisma, Kysely no abstrae SQL, sino que proporciona una API cómoda para escribirlo, manteniendo el control total sobre las consultas generadas. Esto significa que puedes usar toda la potencia de SQL (JOIN, subconsultas, funciones de ventana, CTE) sin tener que lidiar con las limitaciones de un ORM.

El principal problema que resuelve Kysely es la seguridad de tipos en las consultas SQL. En el código JavaScript/TypeScript común, las consultas SQL suelen escribirse como cadenas de texto, lo que provoca errores en tiempo de ejecución (runtime errors): errores tipográficos en nombres de columnas, incompatibilidad de tipos de datos, JOIN incorrectos. Kysely soluciona esto a nivel de compilación: si intentas acceder a una columna inexistente o pasar un tipo de dato incorrecto, TypeScript te mostrará un error antes de ejecutar la aplicación. Esto reduce significativamente el tiempo de depuración y aumenta la fiabilidad del código.

Kysely es ideal para proyectos donde se necesita el máximo rendimiento y control sobre SQL, pero sin renunciar a las ventajas de la tipificación estática. Es compatible con PostgreSQL, MySQL, SQLite y MSSQL, incluye protección integrada contra inyecciones SQL (mediante consultas parametrizadas), soporte para migraciones y generación de tipos a partir del esquema existente de la base de datos. La biblioteca está en desarrollo activo, cuenta con buena documentación y una comunidad activa.

2. Instalación

La instalación de Kysely se realiza mediante npm (o yarn/pnpm). Necesitarás instalar la biblioteca principal y el driver para tu base de datos.

# Paquete principal
npm install kysely

# Para PostgreSQL
npm install pg

# Para MySQL
npm install mysql2

# Para SQLite
npm install better-sqlite3

# Para MSSQL
npm install tedious

Si usas TypeScript, asegúrate de tener instalados los tipos para el driver (normalmente vienen incluidos). Para una mejor experiencia de desarrollo, también se recomienda instalar ts-node para ejecutar archivos TypeScript:

npm install -D ts-node typescript @types/node

Para trabajar con migraciones, instala adicionalmente:

npm install -D @kysely/cli

3. Inicio rápido — ejemplo mínimo funcional

Vamos a crear una aplicación simple que se conecta a una base de datos SQLite, crea una tabla de usuarios y ejecuta varias consultas.

Primero, definimos los tipos para nuestra base de datos:

// types.ts
export interface User {
  id: number;
  name: string;
  email: string;
  age: number | null;
  created_at: Date;
}

export interface Database {
  users: User;
  // Aquí puedes agregar otras tablas
}

Ahora creamos la aplicación principal:

// index.ts
import { Kysely, SqliteDialect } from 'kysely';
import Database from 'better-sqlite3';
import type { Database as MyDatabase } from './types';

// Creamos una instancia de Kysely
const db = new Kysely<MyDatabase>({
  dialect: new SqliteDialect({
    database: new Database('my_database.db'),
  }),
});

async function main() {
  // Creamos la tabla (si no existe)
  await db.schema
    .createTable('users')
    .ifNotExists()
    .addColumn('id', 'integer', (col) => col.primaryKey().autoIncrement())
    .addColumn('name', 'varchar(255)', (col) => col.notNull())
    .addColumn('email', 'varchar(255)', (col) => col.notNull().unique())
    .addColumn('age', 'integer')
    .addColumn('created_at', 'datetime', (col) => col.defaultTo('now()'))
    .execute();

  // Insertamos datos