1. ¿Qué es y por qué usarlo?

ts-sql-query es una potente biblioteca para TypeScript que te permite escribir consultas SQL con tipado seguro (type-safe). Proporciona un DSL (Lenguaje Específico de Dominio) intuitivo para construir consultas SQL, donde cada instrucción es verificada por el compilador de TypeScript contra el esquema de tu base de datos. Esto significa que errores como nombres de tablas mal escritos, campos incorrectos o tipos de datos incompatibles se detectan en tiempo de compilación, no en ejecución.

¿Por qué es importante? En enfoques tradicionales (cadenas SQL en bruto u ORM), los desarrolladores suelen enfrentarse a problemas comunes: errores tipográficos en nombres de columnas, desajustes de tipos y dificultades para refactorizar. ts-sql-query resuelve estos inconvenientes ofreciendo un tipado estricto para todas las operaciones: SELECT, INSERT, UPDATE, DELETE, JOIN, subconsultas, funciones agregadas y mucho más. La biblioteca es compatible con múltiples sistemas de bases de datos (PostgreSQL, MySQL, SQLite, MariaDB, MSSQL) y funciona tanto con controladores directos como con pools de conexiones.

A diferencia de los ORM (como TypeORM o Prisma), ts-sql-query no oculta el SQL detrás de abstracciones, sino que lo integra directamente en tu código TypeScript. Sigues escribiendo SQL, pero con autocompletado, verificación de tipos y sin riesgo de inyección SQL. Es la opción ideal para proyectos donde el rendimiento y el control total sobre las consultas son prioritarios, pero sin renunciar a las ventajas del tipado estático.

2. Instalación

La instalación se realiza a través de npm. Necesitarás instalar la biblioteca principal y el controlador correspondiente a tu base de datos.

# Instalación de la biblioteca principal
npm install ts-sql-query

# Instalación del controlador para PostgreSQL (ejemplo)
npm install pg

# Instalación del controlador para MySQL
npm install mysql2

# Instalación del controlador para SQLite
npm install better-sqlite3

# Instalación del controlador para SQLite (asíncrono)
npm install sql.js

# Instalación de tipos para Node.js (si los usas)
npm install --save-dev @types/node

Una vez instalado el controlador, debes crear una conexión a tu base de datos. ts-sql-query incluye adaptadores para cada controlador compatible.

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

Veamos un ejemplo con PostgreSQL. Crearemos una tabla simple users y ejecutaremos una consulta SELECT.

import { createPool } from 'pg';
import { PostgreSqlConnection } from 'ts-sql-query/connections/PostgreSqlConnection';

// 1. Crear un pool de conexiones
const pool = createPool({
    host: 'localhost',
    port: 5432,
    database: 'testdb',
    user: 'usuario',
    password: 'contraseña',
});

// 2. Crear la clase de conexión
class DBConnection extends PostgreSqlConnection {
    // Aquí puedes definir métodos para trabajar con las tablas
}

// 3. Crear una instancia de conexión
const connection = new DBConnection(pool);

// 4. Definir el tipo para la tabla users
interface User {
    id: number;
    name: string;
    email: string;
    age: number;
}

// 5. Crear un objeto para manejar la tabla
const users = connection.table('users').columns({
    id: 'id',
    name: 'nombre',
    email: 'correo',
    age: 'edad',
});

// 6. Ejecutar la consulta
async function getUsers() {
    const query = connection
        .selectFrom(users)
        .select(users.id, users.name, users.email)
        .where(users.age.greaterThan(18))
        .orderBy(users.name, 'asc');

    const result = await query.executeSelectMany();
    return result;
}

getUsers().then(users => {
    console.log('Usuarios:', users);
}).catch(err => {
    console.error('Error:', err);
});

En este ejemplo creamos una conexión, definimos la tabla y ejecutamos una consulta SELECT. Todos los tipos son verificados por el compilador.