0002. Escolha do ORM¶

Date: 2025-10-08

Status¶

Aprovado

Context¶

O projeto requer uma camada de persistência de dados robusta, segura e produtiva, com integração fluida aos pipelines DevSecOps e compatibilidade com múltiplos bancos relacionais (PostgreSQL, MySQL, SQL Server, SQLite, etc.). Os serviços são majoritariamente desenvolvidos em Node.js/TypeScript, com demandas de:

• Mapeamento tipado e seguro entre objetos e tabelas.
• Geração automática de esquemas e migrações.
• Integração com ferramentas de documentação e testes automatizados.
• Suporte a arquitetura clean e princípios de Domain-Driven Design (DDD).

Alternativas Avaliadas¶

Análise Detalhada¶

# Prisma¶

• Forças:
  • Engine de consultas em Rust, garantindo alto desempenho.
  • Geração automática de tipos TypeScript, eliminando classes manuais.
  • Ferramentas integradas (prisma migrate, prisma studio) facilitam CI/CD e observabilidade.
  • Excelente compatibilidade com GraphQL, REST, NestJS e Next.js.
  • Facilita o princípio "Clean Core" — a lógica de domínio não depende do ORM.
• Fraquezas:
  • Foco exclusivo em TypeScript (não suporta Python/Java).
  • Menor controle manual sobre SQL bruto (embora possível via queryRaw).

# TypeORM¶

• Forças:
  • Baseado em decorators familiares a quem usa NestJS.
  • Amplo suporte a bancos e features como lazy loading.
• Fraquezas:
  • Problemas de consistência de migrações e sincronização de schema.
  • Menor performance e tipagem fraca (muitas validações ocorrem em runtime).
  • Menor previsibilidade em ambientes com CI/CD automatizado.

# SQLAlchemy¶

• Forças:
  • ORM mais maduro do mercado.
  • Extensível, sólido e com controle total sobre SQL.
  • Integração perfeita com frameworks Python (FastAPI, Flask, Django).
• Fraquezas:
  • Requer adoção do stack Python.
  • Menos alinhado com o ecossistema TypeScript e com práticas de tipagem forte no front/back.

Decisão¶

Após análise técnica e estratégica, decidiu-se pela adoção do Prisma ORM como padrão para novos serviços baseados em Node.js/TypeScript. A decisão se fundamenta nos seguintes pontos:

• Produtividade: O Prisma simplifica o ciclo de desenvolvimento e manutenção.
• Segurança e qualidade: Geração de tipos e validações em tempo de build reduzem erros em runtime.
• DevSecOps: O modelo declarativo e CLI integrada facilitam integração com pipelines automatizados.
• Clean Architecture: Separa domínio e persistência de forma clara, evitando acoplamentos desnecessários.
• Performance: Query engine em Rust proporciona ganhos reais de performance e estabilidade.

Consequências¶

# Positivas¶

• Aumento da produtividade dos times.
• Redução de bugs relacionados a inconsistências de schema.
• Melhoria na integração contínua e automação de deploys.
• Maior aderência à cultura Clean Core e Documentation as Code.

# Negativas¶

• Necessidade de treinamento inicial em Prisma CLI e modelagem declarativa.
• Dependência direta do ecossistema Node.js/TypeScript.

Plano de Ação¶

• Criar repositório de referência com boilerplate Prisma + NestJS + PostgreSQL.
• Atualizar guidelines de desenvolvimento no repositório dev-standards.
• Realizar workshop interno sobre Prisma ORM e boas práticas de migração.
• Definir padrões de auditoria e logging a partir do Prisma Client.

Referências¶

• Prisma ORM Documentation
• TypeORM Documentation
• SQLAlchemy Documentation
• Node.js Clean Architecture Principles

Decisão Final:

O Prisma ORM é adotado como o ORM oficial para projetos em Node.js/TypeScript, substituindo o uso de TypeORM em novos desenvolvimentos.