Drizzle ORM

O que Drizzle ORM faz?

Regras

• Definição de esquema: pgTable() / mysqlTable() / sqliteTable() em src/db/schema.ts
• Desenvolvimento: drizzle-kit push para iteração rápida — nenhum arquivo de migração necessário
• Produção: drizzle-kit generate + drizzle-kit migrate para histórico de migrações rastreável
• Consultas type-safe: db.select().from(users).where(eq(users.email, email)) — inferência completa do TypeScript
• Relações: defina com o helper relations() — one() e many() para consultas relacionais com db.query
• Declarações preparadas: db.select().from(users).where(eq(users.id, sql.placeholder("id"))).prepare() — reutilize em caminhos críticos
• Transações: db.transaction(async (tx) => { ... }) — use tx e não db dentro do callback
• Índices: defina inline com .index() ou na configuração da tabela — adicione em colunas usadas em where e orderBy
• Drizzle Studio: npx drizzle-kit studio para navegador visual de banco de dados durante o desenvolvimento

Padrões

// schema.ts
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] }),
}));

// Consulta com relações
const result = await db.query.users.findFirst({
  where: eq(users.id, userId),
  with: { posts: true },
});

Evitar

• drizzle-kit push em produção — use generate + migrate para migrações rastreáveis
• SQL puro quando a API do Drizzle cobre — use o template tag sql apenas para expressões complexas
• Esquecer as definições de relations() — sem elas, consultas relacionais com db.query não funcionarão
• Consultas N+1 — use with em db.query para unir relações em uma única consulta
• Faltar índices em chaves estrangeiras e colunas filtradas — Drizzle não os cria automaticamente