Drizzle ORM

Q: Drizzle suporta NestJS 11?

Sim, via provider customizado que envolve a instância db ou módulos Drizzle da comunidade.

Q: Como eu logoo SQL?

Habilite o logger em drizzle(pool, { logger: true }) apenas em desenvolvimento.

Q: Postgres Serverless?

max pequeno no pool ou driver serverless; veja Ajuste de Pool de Conexão.

Q: Posso usar Drizzle com SQLite para testes?

Sim - troque o driver drizzle-orm/better-sqlite3 no bootstrap de testes.

Q: Chaves primárias compostas?

Suportadas na definição de tabela com configuração tuple primaryKey.

Q: Enums?

pgEnum no schema mapeia para o tipo ENUM do Postgres - migre com cuidado em produção.

Q: Como evitar N+1?

Use joins ou queries relacionais with em uma única viagem - a mesma disciplina que include da Prisma.

Q: ESM no Node 24?

Drizzle é amigável a ESM. Use "type": "module" e sintaxe import em todo o código.

Drizzle é um ORM SQL-first para TypeScript: definições de tabela vivem no código, queries parecem SQL e o runtime permanece fino sobre node-postgres.

Receita

Cartão de referência rápida - pronto para copiar e colar.

// 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;
}

Quando usar isso:

Desenvolvedores querem visibilidade SQL com inferência TypeScript
Tamanho do bundle e overhead de runtime importam (edge workers, pequenos serviços)
Equipe confortável em revisar SQL de migração gerado

Exemplo Funcional

// 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;
  });
}

O que isso demonstra:

Schema como tabelas TypeScript
db.transaction envolve transação Postgres
returning() para resultados de INSERT sem uma segunda query
A mesma sintonia de pool pg se aplica por baixo dos panos

Mergulho Profundo

Migrações com drizzle-kit

npx drizzle-kit generate
npx drizzle-kit migrate

SQL gerado fica na pasta drizzle/ para revisão de PR
Alinhe o CI para rodar migrate antes do deploy da aplicação, o mesmo que a política da Prisma

Joins e Relations

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));

Joins explícitos tornam os planos de query revisáveis nos logs
API de query relacional (db.query.users.findMany({ with: { orders: true } })) disponível quando preferido

Fuga para 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
`);

sql com template mantém a parametrização para fragmentos dinâmicos

Esboço do Plugin Fastify 5

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

Decore uma vez; rotas usam fastify.db para queries
Feche o pool no hook onClose

Armadilhas

Esquecer .limit(1) em buscas únicas - sempre retorna um array. Correção: limit(1) e pegue [0].
Divergência de schema sem migrate no CI - erros de runtime em colunas ausentes. Correção: migrate como portão de deploy.
Misturar Drizzle e Prisma em um único serviço - dois sistemas de migração. Correção: escolha um ORM por deploy.
Filtros inArray grandes - pacotes SQL enormes. Correção: lote de IDs ou padrão de tabela temporária.
Sem UUID padrão no DB - a aplicação deve gerar IDs consistentemente.

Alternativas

Alternativa	Use Quando	Não Use Quando
Prisma	Studio, ergonomia de relations, ecossistema maior	Quer runtime mínimo SQL-first
Kysely	Apenas query builder, sem DSL de schema	Quer kit integrado de schema + migrate
`pg` + arquivos SQL	DBAs controlam todo o SQL	Precisa de inferência TS em colunas
TypeORM	Projetos Nest legados	Greenfield sem custo de migração

FAQs

Drizzle vs Prisma para novas APIs Node?

Drizzle se transparência SQL e peso de runtime importam. Prisma se DSL de schema e velocidade de tooling vencem.

Drizzle suporta NestJS 11?

Sim, via provider customizado que envolve a instância db ou módulos Drizzle da comunidade.

Como eu logoo SQL?

Habilite o logger em drizzle(pool, { logger: true }) apenas em desenvolvimento.

Postgres Serverless?

max pequeno no pool ou driver serverless; veja Ajuste de Pool de Conexão.

Posso usar Drizzle com SQLite para testes?

Sim - troque o driver drizzle-orm/better-sqlite3 no bootstrap de testes.

Chaves primárias compostas?

Suportadas na definição de tabela com configuração tuple primaryKey.

Enums?

pgEnum no schema mapeia para o tipo ENUM do Postgres - migre com cuidado em produção.

Como evitar N+1?

Use joins ou queries relacionais with em uma única viagem - a mesma disciplina que include da Prisma.

ESM no Node 24?

Drizzle é amigável a ESM. Use "type": "module" e sintaxe import em todo o código.

Performance bruta vs Prisma?

Drizzle é tipicamente mais leve; faça benchmark dos seus endpoints, não de inserts "hello-world".

Relacionados

Prisma - ORM schema-first
node-postgres (pg) - driver subjacente
Básicos de Banco de Dados - quando SQL vs documento
Ajuste de Pool de Conexão - dimensionamento de pool
Boas Práticas de Banco de Dados - política de migração

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.

Receita

Cartão de referência rápida - pronto para copiar e colar.

// 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;
}

Quando usar isso:

Desenvolvedores querem visibilidade SQL com inferência TypeScript
Tamanho do bundle e overhead de runtime importam (edge workers, pequenos serviços)
Equipe confortável em revisar SQL de migração gerado

Exemplo Funcional

// 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;
  });
}

O que isso demonstra:

Schema como tabelas TypeScript
db.transaction envolve transação Postgres
returning() para resultados de INSERT sem uma segunda query
A mesma sintonia de pool pg se aplica por baixo dos panos

Mergulho Profundo

Migrações com drizzle-kit

npx drizzle-kit generate
npx drizzle-kit migrate

SQL gerado fica na pasta drizzle/ para revisão de PR
Alinhe o CI para rodar migrate antes do deploy da aplicação, o mesmo que a política da Prisma

Joins e Relations

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));

Joins explícitos tornam os planos de query revisáveis nos logs
API de query relacional (db.query.users.findMany({ with: { orders: true } })) disponível quando preferido

Fuga para 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
`);

sql com template mantém a parametrização para fragmentos dinâmicos

Esboço do Plugin Fastify 5

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

Decore uma vez; rotas usam fastify.db para queries
Feche o pool no hook onClose

Armadilhas

Esquecer .limit(1) em buscas únicas - sempre retorna um array. Correção: limit(1) e pegue [0].
Divergência de schema sem migrate no CI - erros de runtime em colunas ausentes. Correção: migrate como portão de deploy.
Misturar Drizzle e Prisma em um único serviço - dois sistemas de migração. Correção: escolha um ORM por deploy.
Filtros inArray grandes - pacotes SQL enormes. Correção: lote de IDs ou padrão de tabela temporária.
Sem UUID padrão no DB - a aplicação deve gerar IDs consistentemente.

Alternativas

Alternativa	Use Quando	Não Use Quando
Prisma	Studio, ergonomia de relations, ecossistema maior	Quer runtime mínimo SQL-first
Kysely	Apenas query builder, sem DSL de schema	Quer kit integrado de schema + migrate
`pg` + arquivos SQL	DBAs controlam todo o SQL	Precisa de inferência TS em colunas
TypeORM	Projetos Nest legados	Greenfield sem custo de migração

FAQs

Drizzle vs Prisma para novas APIs Node?

Drizzle se transparência SQL e peso de runtime importam. Prisma se DSL de schema e velocidade de tooling vencem.

Drizzle suporta NestJS 11?

Sim, via provider customizado que envolve a instância db ou módulos Drizzle da comunidade.

Como eu logoo SQL?

Habilite o logger em drizzle(pool, { logger: true }) apenas em desenvolvimento.

Postgres Serverless?

max pequeno no pool ou driver serverless; veja Ajuste de Pool de Conexão.

Posso usar Drizzle com SQLite para testes?

Sim - troque o driver drizzle-orm/better-sqlite3 no bootstrap de testes.

Chaves primárias compostas?

Suportadas na definição de tabela com configuração tuple primaryKey.

Enums?

pgEnum no schema mapeia para o tipo ENUM do Postgres - migre com cuidado em produção.

Como evitar N+1?

Use joins ou queries relacionais with em uma única viagem - a mesma disciplina que include da Prisma.

ESM no Node 24?

Drizzle é amigável a ESM. Use "type": "module" e sintaxe import em todo o código.

Performance bruta vs Prisma?

Drizzle é tipicamente mais leve; faça benchmark dos seus endpoints, não de inserts "hello-world".

Relacionados

Prisma - ORM schema-first
node-postgres (pg) - driver subjacente
Básicos de Banco de Dados - quando SQL vs documento
Ajuste de Pool de Conexão - dimensionamento de pool
Boas Práticas de Banco de Dados - política de migração

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.

Drizzle ORM

Buscar na documentação

Drizzle ORM