Drizzle ORM
Reglas
- Definición de esquemas:
pgTable() / mysqlTable() / sqliteTable() en src/db/schema.ts
- Desarrollo:
drizzle-kit push para iteración rápida — no se necesitan archivos de migración
- Producción:
drizzle-kit generate + drizzle-kit migrate para un historial de migraciones rastreable
- Consultas tipadas:
db.select().from(users).where(eq(users.email, email)) — inferencia completa de TypeScript
- Relaciones: definir con el helper
relations() — one() y many() para consultas relacionales con db.query
- Sentencias preparadas:
db.select().from(users).where(eq(users.id, sql.placeholder("id"))).prepare() — reutilizar para rutas críticas
- Transacciones:
db.transaction(async (tx) => { ... }) — usar tx en lugar de db dentro del callback
- Índices: definir en línea con
.index() o en la configuración de la tabla — agregar en columnas usadas en where y orderBy
- Drizzle Studio:
npx drizzle-kit studio para un navegador visual de base de datos durante el desarrollo
Patrones
import { pgTable, text, timestamp, uuid, integer } from "drizzle-orm/pg-core";
import { relations } from "drizzle-orm";
export const users = pgTable("users", {
id: uuid("id").primaryKey().defaultRandom(),
name: text("name").notNull(),
email: text("email").notNull().unique(),
createdAt: timestamp("created_at").defaultNow().notNull(),
});
export const posts = pgTable("posts", {
id: uuid("id").primaryKey().defaultRandom(),
title: text("title").notNull(),
authorId: uuid("author_id").references(() => users.id).notNull(),
});
export const usersRelations = relations(users, ({ many }) => ({
posts: many(posts),
}));
export const postsRelations = relations(posts, ({ one }) => ({
author: one(users, { fields: [posts.authorId], references: [users.id] }),
}));
const result = await db.query.users.findFirst({
where: eq(users.id, userId),
with: { posts: true },
});
Evitar
drizzle-kit push en producción — usar generate + migrate para migraciones rastreadas
- SQL crudo cuando la API de Drizzle lo cubra — usar la etiqueta de plantilla
sql solo para expresiones complejas
- Olvidar las definiciones de
relations() — sin ellas, las consultas relacionales de db.query no funcionarán
- Consultas N+1 — usar
with en db.query para unir relaciones en una sola consulta
- Falta de índices en claves foráneas y columnas filtradas — Drizzle no los crea automáticamente