Desenvolvimento de Banco de Dados Schema-First com Drizzle

Seus tipos TypeScript dizem uma coisa. Seu banco de dados diz outra. As consultas falham em tempo de execução, e você fica depurando incompatibilidades que nunca deveriam ter existido.

O design de banco de dados schema-first com Drizzle resolve isso tornando seu código TypeScript a única fonte de verdade. Suas definições de schema orientam tanto os tipos da sua aplicação quanto a estrutura do seu banco de dados, eliminando a desconexão que causa surpresas em tempo de execução.

Este artigo explica como funciona o desenvolvimento schema-first com Drizzle ORM, quando usar diferentes fluxos de trabalho de migração e armadilhas comuns a evitar.

O Que Schema-First Realmente Significa no Drizzle

Drizzle é fundamentalmente code-first. Você define tabelas, colunas e relacionamentos em TypeScript, e essa definição se torna autoritativa para tudo downstream—consultas, migrações e inferência de tipos.

import { pgTable, serial, text, timestamp } from "drizzle-orm/pg-core"

export const posts = pgTable("posts", {
  id: serial().primaryKey(),
  title: text().notNull(),
  content: text(),
  createdAt: timestamp().defaultNow(),
})

Este arquivo de schema serve a propósitos duplos. Drizzle ORM o usa para consultas type-safe. Drizzle Kit o usa para gerar ou aplicar mudanças no banco de dados.

O termo “schema-first” aqui significa que suas definições TypeScript lideram. O banco de dados segue.

Code-First vs Database-First: Entendendo a Distinção

Fluxos de trabalho tradicionais database-first tratam o banco de dados como autoritativo. Você cria tabelas manualmente ou com scripts SQL, depois gera código da aplicação a partir da estrutura existente.

Comparações entre code-first e database-first frequentemente confundem esses termos. No contexto do Drizzle:

• Code-first: Seu schema TypeScript dirige as mudanças no banco de dados
• Database-first: Você puxa a estrutura do banco de dados existente para TypeScript usando drizzle-kit pull

Drizzle suporta ambos. Para projetos greenfield, code-first é tipicamente mais limpo. Para cenários brownfield—entrando em um projeto com banco de dados existente—a introspecção via pull permite começar rapidamente.

O Fluxo de Trabalho do Drizzle Kit: Push vs Generate

Drizzle Kit oferece dois caminhos principais para aplicar mudanças de schema ao seu banco de dados.

Schema Push para Iteração Rápida

npx drizzle-kit push

Push compara seu schema ao banco de dados e aplica mudanças diretamente. Sem arquivos de migração. Sem etapa de revisão.

Isso funciona bem para:

• Projetos solo
• Prototipagem inicial
• Bancos de dados de desenvolvimento local que você pode recriar

O trade-off é visibilidade. Você não terá um registro do que mudou ou quando.

Migrações Geradas para Segurança da Equipe

npx drizzle-kit generate
npx drizzle-kit migrate

generate cria arquivos de migração SQL. migrate os aplica. Os arquivos vivem no controle de versão, criando uma trilha de auditoria.

Esta abordagem se adequa a:

• Ambientes de equipe onde mudanças precisam de revisão
• Implantações em produção requerendo capacidade de rollback
• Cenários de conformidade necessitando documentação de mudanças

Nenhum método é universalmente correto. O fluxo de trabalho do Drizzle Kit acomoda ambos baseado no seu contexto.

Configurando o Drizzle Kit

Seu drizzle.config.ts diz ao Drizzle Kit onde encontrar schemas e armazenar migrações:

import { defineConfig } from "drizzle-kit"

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/db/schema.ts",
  out: "./drizzle/migrations",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
})

Drizzle suporta os principais bancos de dados SQL incluindo PostgreSQL, MySQL e SQLite/libSQL, com dialetos adicionais como MSSQL e CockroachDB emergindo. A configuração permanece amplamente consistente entre bancos de dados—apenas o dialeto e opções específicas do driver mudam.

Armadilhas Comuns a Evitar

O desenvolvimento schema-first com Drizzle não é sem pontos de atrito.

Tabelas existentes requerem manuseio cuidadoso. Se você está adotando Drizzle em um banco de dados com tabelas existentes, seu primeiro generate pode produzir migrações que tentam recriar tudo. Use pull primeiro para sincronizar seu arquivo de schema com a realidade.

Introspecção pode produzir diffs ruidosos. Puxar de um banco de dados pode incluir nomes de constraints ou defaults que diferem do que você escreveria manualmente. Generates subsequentes podem sinalizar isso como mudanças mesmo quando nada significativo mudou.

Incompatibilidades de nomes de constraints causam migrações inesperadas. Drizzle gera nomes de constraints deterministicamente. Se seu banco de dados tem nomes diferentes (de criação manual ou outra ferramenta), você verá instruções ALTER que renomeiam constraints sem mudar o comportamento.

Migrações em tempo de execução precisam de tratamento de erros. Se você está aplicando migrações programaticamente durante a implantação, envolva-as em tratamento de erros adequado. Uma migração falhada no meio da implantação pode deixar seu banco de dados em um estado inconsistente.

Quando Schema-First Melhora Seu Fluxo de Trabalho

O desenvolvimento schema-first com Drizzle ORM brilha quando:

• Você quer garantias em tempo de compilação de que consultas correspondem ao seu schema
• Múltiplos desenvolvedores precisam coordenar mudanças no banco de dados
• Você está implantando em ambientes edge ou serverless onde o tamanho do bundle importa
• Você prefere sintaxe similar a SQL em vez de query builders abstraídos

Drizzle Studio complementa este fluxo de trabalho com uma interface visual para navegar dados e testar consultas contra seu schema.

Conclusão

Comece com seu arquivo de schema. Defina tabelas que correspondam ao seu domínio. Use push enquanto itera localmente, depois mude para generate e migrate antes de envolver colegas de equipe ou implantar em produção.

O objetivo não é escolher um fluxo de trabalho para sempre—é entender os trade-offs para que você escolha a ferramenta certa para cada fase do desenvolvimento.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.