1. O que é e por que usar

ts-sql-query é uma biblioteca poderosa para TypeScript que permite escrever consultas SQL com suporte total a tipos (type-safe). Ela oferece um DSL (Domain-Specific Language) prático para construir consultas SQL, onde cada query é verificada pelo compilador TypeScript quanto à conformidade com o esquema do banco de dados. Isso significa que erros em nomes de tabelas, campos ou tipos de dados são detectados em tempo de compilação, não em execução.

Por que usar? Em abordagens tradicionais (strings SQL brutas ou ORMs), desenvolvedores enfrentam problemas como erros de digitação em nomes de colunas, incompatibilidade de tipos e dificuldade em refatorar. O ts-sql-query resolve esses problemas fornecendo tipagem rigorosa para todas as operações: SELECT, INSERT, UPDATE, DELETE, JOIN, subconsultas, funções agregadas e muito mais. A biblioteca suporta diversos SGBDs (PostgreSQL, MySQL, SQLite, MariaDB, MSSQL) e funciona tanto com drivers diretamente quanto com pools de conexão.

Diferente de ORMs (como TypeORM ou Prisma), o ts-sql-query não esconde o SQL por trás de abstrações; ele torna o SQL parte do código TypeScript. Você continua escrevendo SQL, mas com autocomplete, verificação de tipos e sem risco de injeção SQL. É a escolha ideal para projetos onde desempenho e controle total sobre as consultas são essenciais, mas você ainda quer aproveitar os benefícios da tipagem estática.

2. Instalação

A instalação é feita via npm. Você precisará instalar a biblioteca principal e o driver do seu banco de dados.

# Instalação da biblioteca principal
npm install ts-sql-query

# Instalação do driver para PostgreSQL (exemplo)
npm install pg

# Instalação do driver para MySQL
npm install mysql2

# Instalação do driver para SQLite
npm install better-sqlite3

# Instalação do driver para SQLite (assíncrono)
npm install sql.js

# Instalação dos tipos para Node.js (se necessário)
npm install --save-dev @types/node

Após instalar o driver, você precisa criar uma conexão com o banco de dados. O ts-sql-query fornece adaptadores para cada driver.

3. Início rápido — exemplo mínimo funcional

Vamos ver um exemplo para PostgreSQL. Criaremos uma tabela simples users e executaremos uma consulta SELECT.

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

// 1. Criar um pool de conexões
const pool = createPool({
    host: 'localhost',
    port: 5432,
    database: 'testdb',
    user: 'usuario',
    password: 'senha',
});

// 2. Criar a classe de conexão
class DBConnection extends PostgreSqlConnection {
    // Aqui você pode definir métodos para trabalhar com as tabelas
}

// 3. Criar uma instância da conexão
const connection = new DBConnection(pool);

// 4. Definir o tipo para a tabela users
interface User {
    id: number;
    name: string;
    email: string;
    age: number;
}

// 5. Criar um objeto para trabalhar com a tabela
const users = connection.table('users').columns({
    id: 'id',
    name: 'nome',
    email: 'email',
    age: 'idade',
});

// 6. Executar a 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('Usuários:', users);
}).catch(err => {
    console.error('Erro:', err);
});

Neste exemplo, criamos uma conexão, definimos a tabela e executamos uma consulta SELECT. Todos os tipos são verificados pelo compilador.