Drizzle ORM

Q: ¿Cómo registro SQL?

Habilita el logger en drizzle(pool, { logger: true }) solo en desarrollo.

Q: ¿Postgres sin servidor?

max pequeño en el pool o controlador sin servidor; consulta Ajuste del pool de conexiones.

Q: ¿Puedo usar Drizzle con SQLite para pruebas?

Sí, cambia el controlador drizzle-orm/better-sqlite3 en el arranque de la prueba.

Q: ¿Enums?

pgEnum en el esquema se mapea al tipo ENUM de Postgres; migra con cuidado en producción.

Q: ¿Cómo evito N+1?

Usa uniones o consultas relacionales with en un solo viaje de ida y vuelta, la misma disciplina que include de Prisma.

Q: ¿ESM en Node 24?

Drizzle es compatible con ESM. Usa "type": "module" y la sintaxis import en todo el proyecto.

Drizzle es un ORM SQL-first para TypeScript: las definiciones de tablas viven en el código, las consultas se sienten como SQL y el tiempo de ejecución se mantiene ligero sobre node-postgres.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

// src/db/schema.ts
import { pgTable, text, timestamp, integer } from "drizzle-orm/pg-core";
 
export const users = pgTable("users", {
  id: text("id").primaryKey(),
  email: text("email").notNull().unique(),
  createdAt: timestamp("created_at").defaultNow().notNull(),
});
 
export const orders = pgTable("orders", {
  id: text("id").primaryKey(),
  userId: text("user_id").notNull().references(() => users.id),
  totalCents: integer("total_cents").notNull(),
});

import { drizzle } from "drizzle-orm/node-postgres";
import pg from "pg";
import { eq } from "drizzle-orm";
import { users } from "./schema";
 
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
export const db = drizzle(pool);
 
export async function findUserByEmail(email: string) {
  const rows = await db.select().from(users).where(eq(users.email, email)).limit(1);
  return rows[0] ?? null;
}

Cuándo usarlo:

Los desarrolladores quieren visibilidad SQL con inferencia de TypeScript
El tamaño del paquete y la sobrecarga del tiempo de ejecución importan (trabajadores de borde, servicios pequeños)
El equipo se siente cómodo revisando el SQL de migración generado

Ejemplo de trabajo

// src/db/index.ts
import { drizzle } from "drizzle-orm/node-postgres";
import pg from "pg";
import * as schema from "./schema";
 
const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10,
});
 
export const db = drizzle(pool, { schema });
 
// src/repositories/order-repo.ts
import { db } from "../db";
import { orders, orderItems } from "../db/schema";
import { eq } from "drizzle-orm";
 
export async function createOrder(
  userId: string,
  items: { sku: string; qty: number; priceCents: number }[]
) {
  const totalCents = items.reduce((s, i) => s + i.qty * i.priceCents, 0);
 
  return db.transaction(async (tx) => {
    const [order] = await tx
      .insert(orders)
      .values({ id: crypto.randomUUID(), userId, totalCents })
      .returning();
 
    await tx.insert(orderItems).values(
      items.map((i) => ({
        id: crypto.randomUUID(),
        orderId: order.id,
        sku: i.sku,
        qty: i.qty,
        priceCents: i.priceCents,
      }))
    );
 
    return order;
  });
}

Lo que esto demuestra:

Esquema como tablas de TypeScript
db.transaction envuelve la transacción de Postgres
returning() para resultados de INSERT sin una segunda consulta
La misma optimización de pool de pg se aplica por debajo

Análisis profundo

Migraciones con drizzle-kit

npx drizzle-kit generate
npx drizzle-kit migrate

El SQL generado reside en la carpeta drizzle/ para revisión de PR
Alinea CI para ejecutar la migración antes del despliegue de la aplicación, igual que la política de Prisma

Uniones y relaciones

import { db } from "./db";
import { users, orders } from "./schema";
import { eq } from "drizzle-orm";
 
const rows = await db
  .select({
    userId: users.id,
    email: users.email,
    orderId: orders.id,
    totalCents: orders.totalCents,
  })
  .from(users)
  .innerJoin(orders, eq(orders.userId, users.id))
  .where(eq(users.id, userId));

Las uniones explícitas hacen que los planes de consulta sean revisables en los registros
La API de consulta relacional (db.query.users.findMany({ with: { orders: true } })) está disponible cuando se prefiere

Escape de SQL

import { sql } from "drizzle-orm";
 
await db.execute(sql`
  SELECT date_trunc('day', created_at) AS day, COUNT(*)::int AS cnt
  FROM orders GROUP BY 1
`);

La plantilla sql etiquetada mantiene la parametrización para fragmentos dinámicos

Bosquejo de plugin Fastify 5

import fp from "fastify-plugin";
import { db } from "./db";
 
export const dbPlugin = fp(async (fastify) => {
  fastify.decorate("db", db);
});

Decora una vez; las rutas usan fastify.db para las consultas
Cierra el pool en el hook onClose

Errores comunes

Olvidar .limit(1) en búsquedas únicas - siempre devuelve un array. Solución: limit(1) y toma [0].
Deriva del esquema sin migrar en CI - errores en tiempo de ejecución en columnas faltantes. Solución: migrar la puerta de despliegue.
Mezclar Drizzle y Prisma en un servicio - dos sistemas de migración. Solución: elige un ORM por desplegable.
Filtros inArray grandes - paquetes SQL enormes. Solución: agrupa IDs o patrón de tabla temporal.
Sin UUID predeterminado en la DB - la aplicación debe generar IDs de forma consistente.

Alternativas

Alternativa	Usar cuando	No usar cuando
Prisma	Studio, ergonomía de relaciones, ecosistema más grande	Quieres un tiempo de ejecución mínimo SQL-first
Kysely	Solo constructor de consultas, sin DSL de esquema	Quieres un esquema integrado + kit de migración
`pg` + archivos SQL	Los DBA son dueños de todo el SQL	Necesitas inferencia de TS en las columnas
TypeORM	Proyectos Nest heredados	Greenfield sin costo de migración

Preguntas frecuentes

¿Drizzle vs Prisma para nuevas API de Node?

Drizzle si la transparencia SQL y el peso del tiempo de ejecución importan. Prisma si el DSL del esquema y la velocidad de las herramientas ganan.

¿Drizzle es compatible con NestJS 11?

Sí, a través de un proveedor personalizado que envuelve la instancia db o módulos Drizzle de la comunidad.

¿Cómo registro SQL?

Habilita el logger en drizzle(pool, { logger: true }) solo en desarrollo.

¿Postgres sin servidor?

max pequeño en el pool o controlador sin servidor; consulta Ajuste del pool de conexiones.

¿Puedo usar Drizzle con SQLite para pruebas?

Sí, cambia el controlador drizzle-orm/better-sqlite3 en el arranque de la prueba.

¿Claves primarias compuestas?

Soportado en la definición de tabla con la configuración de clave primaria de tupla.

¿Enums?

pgEnum en el esquema se mapea al tipo ENUM de Postgres; migra con cuidado en producción.

¿Cómo evito N+1?

Usa uniones o consultas relacionales with en un solo viaje de ida y vuelta, la misma disciplina que include de Prisma.

¿ESM en Node 24?

Drizzle es compatible con ESM. Usa "type": "module" y la sintaxis import en todo el proyecto.

¿Rendimiento bruto vs Prisma?

Drizzle es típicamente más ligero; compara tus endpoints, no las inserciones de "hola mundo".

Relacionado

Prisma - ORM schema-first
node-postgres (pg) - controlador subyacente
Conceptos básicos de bases de datos - cuándo SQL vs documento
Ajuste del pool de conexiones - dimensionamiento del pool
Mejores prácticas de bases de datos - política de migración

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

// src/db/schema.ts
import { pgTable, text, timestamp, integer } from "drizzle-orm/pg-core";
 
export const users = pgTable("users", {
  id: text("id").primaryKey(),
  email: text("email").notNull().unique(),
  createdAt: timestamp("created_at").defaultNow().notNull(),
});
 
export const orders = pgTable("orders", {
  id: text("id").primaryKey(),
  userId: text("user_id").notNull().references(() => users.id),
  totalCents: integer("total_cents").notNull(),
});

import { drizzle } from "drizzle-orm/node-postgres";
import pg from "pg";
import { eq } from "drizzle-orm";
import { users } from "./schema";
 
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
export const db = drizzle(pool);
 
export async function findUserByEmail(email: string) {
  const rows = await db.select().from(users).where(eq(users.email, email)).limit(1);
  return rows[0] ?? null;
}

Cuándo usarlo:

Los desarrolladores quieren visibilidad SQL con inferencia de TypeScript
El tamaño del paquete y la sobrecarga del tiempo de ejecución importan (trabajadores de borde, servicios pequeños)
El equipo se siente cómodo revisando el SQL de migración generado

Ejemplo de trabajo

// src/db/index.ts
import { drizzle } from "drizzle-orm/node-postgres";
import pg from "pg";
import * as schema from "./schema";
 
const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10,
});
 
export const db = drizzle(pool, { schema });
 
// src/repositories/order-repo.ts
import { db } from "../db";
import { orders, orderItems } from "../db/schema";
import { eq } from "drizzle-orm";
 
export async function createOrder(
  userId: string,
  items: { sku: string; qty: number; priceCents: number }[]
) {
  const totalCents = items.reduce((s, i) => s + i.qty * i.priceCents, 0);
 
  return db.transaction(async (tx) => {
    const [order] = await tx
      .insert(orders)
      .values({ id: crypto.randomUUID(), userId, totalCents })
      .returning();
 
    await tx.insert(orderItems).values(
      items.map((i) => ({
        id: crypto.randomUUID(),
        orderId: order.id,
        sku: i.sku,
        qty: i.qty,
        priceCents: i.priceCents,
      }))
    );
 
    return order;
  });
}

Lo que esto demuestra:

Esquema como tablas de TypeScript
db.transaction envuelve la transacción de Postgres
returning() para resultados de INSERT sin una segunda consulta
La misma optimización de pool de pg se aplica por debajo

Análisis profundo

Migraciones con drizzle-kit

npx drizzle-kit generate
npx drizzle-kit migrate

El SQL generado reside en la carpeta drizzle/ para revisión de PR
Alinea CI para ejecutar la migración antes del despliegue de la aplicación, igual que la política de Prisma

Uniones y relaciones

import { db } from "./db";
import { users, orders } from "./schema";
import { eq } from "drizzle-orm";
 
const rows = await db
  .select({
    userId: users.id,
    email: users.email,
    orderId: orders.id,
    totalCents: orders.totalCents,
  })
  .from(users)
  .innerJoin(orders, eq(orders.userId, users.id))
  .where(eq(users.id, userId));

Las uniones explícitas hacen que los planes de consulta sean revisables en los registros
La API de consulta relacional (db.query.users.findMany({ with: { orders: true } })) está disponible cuando se prefiere

Escape de SQL

import { sql } from "drizzle-orm";
 
await db.execute(sql`
  SELECT date_trunc('day', created_at) AS day, COUNT(*)::int AS cnt
  FROM orders GROUP BY 1
`);

La plantilla sql etiquetada mantiene la parametrización para fragmentos dinámicos

Bosquejo de plugin Fastify 5

import fp from "fastify-plugin";
import { db } from "./db";
 
export const dbPlugin = fp(async (fastify) => {
  fastify.decorate("db", db);
});

Decora una vez; las rutas usan fastify.db para las consultas
Cierra el pool en el hook onClose

Errores comunes

Olvidar .limit(1) en búsquedas únicas - siempre devuelve un array. Solución: limit(1) y toma [0].
Deriva del esquema sin migrar en CI - errores en tiempo de ejecución en columnas faltantes. Solución: migrar la puerta de despliegue.
Mezclar Drizzle y Prisma en un servicio - dos sistemas de migración. Solución: elige un ORM por desplegable.
Filtros inArray grandes - paquetes SQL enormes. Solución: agrupa IDs o patrón de tabla temporal.
Sin UUID predeterminado en la DB - la aplicación debe generar IDs de forma consistente.

Alternativas

Alternativa	Usar cuando	No usar cuando
Prisma	Studio, ergonomía de relaciones, ecosistema más grande	Quieres un tiempo de ejecución mínimo SQL-first
Kysely	Solo constructor de consultas, sin DSL de esquema	Quieres un esquema integrado + kit de migración
`pg` + archivos SQL	Los DBA son dueños de todo el SQL	Necesitas inferencia de TS en las columnas
TypeORM	Proyectos Nest heredados	Greenfield sin costo de migración

Preguntas frecuentes

¿Drizzle vs Prisma para nuevas API de Node?

Drizzle si la transparencia SQL y el peso del tiempo de ejecución importan. Prisma si el DSL del esquema y la velocidad de las herramientas ganan.

¿Drizzle es compatible con NestJS 11?

Sí, a través de un proveedor personalizado que envuelve la instancia db o módulos Drizzle de la comunidad.

¿Cómo registro SQL?

Habilita el logger en drizzle(pool, { logger: true }) solo en desarrollo.

¿Postgres sin servidor?

max pequeño en el pool o controlador sin servidor; consulta Ajuste del pool de conexiones.

¿Puedo usar Drizzle con SQLite para pruebas?

Sí, cambia el controlador drizzle-orm/better-sqlite3 en el arranque de la prueba.

¿Claves primarias compuestas?

Soportado en la definición de tabla con la configuración de clave primaria de tupla.

¿Enums?

pgEnum en el esquema se mapea al tipo ENUM de Postgres; migra con cuidado en producción.

¿Cómo evito N+1?

Usa uniones o consultas relacionales with en un solo viaje de ida y vuelta, la misma disciplina que include de Prisma.

¿ESM en Node 24?

Drizzle es compatible con ESM. Usa "type": "module" y la sintaxis import en todo el proyecto.

¿Rendimiento bruto vs Prisma?

Drizzle es típicamente más ligero; compara tus endpoints, no las inserciones de "hola mundo".

Relacionado

Prisma - ORM schema-first
node-postgres (pg) - controlador subyacente
Conceptos básicos de bases de datos - cuándo SQL vs documento
Ajuste del pool de conexiones - dimensionamiento del pool
Mejores prácticas de bases de datos - política de migración

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Drizzle ORM

Buscar en la documentación

Drizzle ORM