Drizzle ORM para TypeScript: Guía completa

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

Drizzle ORM es una biblioteca moderna, ligera y type-safe de ORM (Object-Relational Mapping) para TypeScript y JavaScript. A diferencia de ORM pesadas como TypeORM o Sequelize, Drizzle está diseñada con un enfoque en el rendimiento, la previsibilidad y la integración total con el sistema de tipos de TypeScript. No intenta ocultar SQL, sino que ofrece una forma cómoda y segura de escribir consultas SQL, manteniendo el control total sobre el código generado.

El objetivo principal de Drizzle es liberar al desarrollador de escribir cadenas SQL en bruto y de tipar manualmente los resultados de las consultas. Describes el esquema de la base de datos en código TypeScript, y Drizzle infiere automáticamente los tipos para todas las tablas, relaciones y consultas. Esto significa que los errores relacionados con nombres de columnas incorrectos, tipos de datos equivocados o campos faltantes se detectan en tiempo de compilación, no en tiempo de ejecución. La biblioteca es compatible con PostgreSQL, MySQL, SQLite y otras bases de datos populares.

Drizzle es ideal para proyectos donde el rendimiento y el control sobre SQL son importantes, pero sin renunciar a las ventajas de una ORM: autocompletado en el IDE, verificación de tipos y descripción declarativa del esquema. Se usa a menudo junto con Next.js, NestJS, Express y otros frameworks. Gracias a su ligereza (aproximadamente 7KB comprimido con gzip) y su ausencia de magia, Drizzle es una excelente opción tanto para proyectos pequeños como para grandes aplicaciones empresariales.

2. Instalación

La instalación de Drizzle ORM y su herramienta CLI (Drizzle Kit) se realiza mediante npm o yarn. La elección del driver depende de la base de datos que utilices.

# Para PostgreSQL
npm install drizzle-orm pg
npm install -D drizzle-kit @types/pg

# Para MySQL
npm install drizzle-orm mysql2
npm install -D drizzle-kit @types/node

# Para SQLite
npm install drizzle-orm better-sqlite3
npm install -D drizzle-kit @types/better-sqlite3

Después de la instalación, debes crear un archivo de configuración drizzle.config.ts para Drizzle Kit:

import type { Config } from "drizzle-kit";

export default {
  schema: "./src/db/schema.ts",
  out: "./drizzle",
  dialect: "postgresql", // o "mysql", "sqlite"
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
} satisfies Config;

3. Inicio rápido

Un ejemplo mínimo funcional para PostgreSQL. Primero definimos el esquema, luego creamos la conexión y ejecutamos una consulta.

// src/db/schema.ts
import { pgTable, serial, text, integer } from "drizzle-orm/pg-core";

export const users = pgTable("users", {
  id: serial("id").primaryKey(),
  name: text("name").notNull(),
  age: integer("age"),
});

// src/index.ts
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { users } from "./db/schema";
import { eq } from "drizzle-orm";

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

const db = drizzle(pool);

async function main() {
  // Insertar datos
  const newUser = await db.insert(users).values({
    name: "Alice",
    age: 30,
  }).returning();
  console.log("Usuario creado:", newUser);

  // Consultar datos
  const allUsers = await db.select().from(users);
  console.log("Todos los usuarios:", allUsers);

  // Consulta con condición
  const user = await db.select()
    .from(users)
    .where(eq(users.name, "Alice"));
  console.log("Usuario encontrado:", user);
}

main().catch(console.error);