Drizzle ORM para TypeScript: Guia Completo

1. O que é Drizzle ORM e por que usar?

Drizzle ORM é uma biblioteca ORM (Object-Relational Mapping) moderna, leve e type-safe para TypeScript e JavaScript. Diferente de ORMs pesados como TypeORM ou Sequelize, o Drizzle foi projetado com foco em desempenho, previsibilidade e integração total com o sistema de tipos do TypeScript. Ele não tenta esconder o SQL; pelo contrário, oferece uma maneira conveniente e segura de escrever consultas SQL, mantendo total controle sobre o código gerado.

O principal objetivo do Drizzle é eliminar a necessidade de escrever strings SQL brutas e tipar manualmente os resultados das consultas. Você define o esquema do banco de dados em código TypeScript, e o Drizzle infere automaticamente os tipos para todas as tabelas, relacionamentos e consultas. Isso significa que erros relacionados a nomes de colunas incorretos, tipos de dados errados ou campos ausentes são detectados em tempo de compilação, não em execução. A biblioteca suporta PostgreSQL, MySQL, SQLite e outros bancos de dados populares.

Drizzle é ideal para projetos onde desempenho e controle sobre SQL são importantes, mas você ainda quer os benefícios de uma ORM: autocompletar na IDE, verificação de tipos e descrição declarativa do esquema. É frequentemente usado com Next.js, NestJS, Express e outros frameworks. Graças à sua leveza (cerca de 7KB gzipped) e ausência de "mágica", o Drizzle é uma excelente escolha tanto para projetos pequenos quanto para grandes aplicações enterprise.

2. Instalação

A instalação do Drizzle ORM e sua ferramenta CLI (Drizzle Kit) é feita via npm ou yarn. A escolha do driver depende do banco de dados utilizado.

# 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

Após a instalação, crie um arquivo de configuração drizzle.config.ts para o Drizzle Kit:

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

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

3. Início Rápido

Um exemplo mínimo funcional para PostgreSQL. Primeiro, definimos o esquema, depois criamos a conexão e executamos as consultas.

// 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() {
  // Inserir dados
  const newUser = await db.insert(users).values({
    name: "Alice",
    age: 30,
  }).returning();
  console.log("Usuário criado:", newUser);

  // Selecionar dados
  const allUsers = await db.select().from(users);
  console.log("Todos os usuários:", allUsers);

  // Selecionar com condição
  const user = await db.select()
    .from(users)
    .where(eq(users.name, "Alice"));
  console.log("Usuário encontrado:", user);
}

main().catch(console.error);