Banco de Dados com Prisma ORM: O Melhor para Produtividade

Olá! Felipe aqui. Hoje quero compartilhar uma das decisões mais importantes que tomei para o SaaS Boilerplate v2.0: a escolha do Prisma como nossa ferramenta de banco de dados. Depois de anos trabalhando com diversos ORMs e construtores de consultas, descobri que o Prisma é o ponto ideal para construir aplicações SaaS modernas.

Minha Jornada até o Prisma

Utilizo o Prisma desde o lançamento da versão 2, por volta de 2020, quando ele revolucionou a forma como trabalhamos com bancos de dados em TypeScript. Ao longo dos anos, experimentei de tudo - consultas SQL puras, Sequelize, TypeORM, Knex, e até mesmo construí minhas próprias camadas de acesso a dados. Cada abordagem tinha seus pontos fortes, mas também apresentava dificuldades significativas que atrasavam o desenvolvimento.

O que me atraiu ao Prisma foi a combinação de segurança de tipos, experiência do desenvolvedor e performance. É a primeira ferramenta de banco de dados que realmente me tornou mais produtivo em vez de trabalhar contra mim. A segurança de tipos que o Prisma oferece é incomparável, e é um dos principais motivos pelos quais decidimos manter o SaaS Boilerplate construído sobre ele.

A Revolução da Segurança de Tipos

Como alguém que passou inúmeras horas depurando problemas relacionados a banco de dados, a segurança de tipos do Prisma revolucionou meu fluxo de trabalho:

• Sem Mais Surpresas em Tempo de Execução: Meu IDE detecta a maioria dos erros de banco de dados antes mesmo de eu executar o código
• Autocompletar que Realmente Funciona: O suporte do IntelliSense é mágico - raramente preciso consultar a documentação
• Schema como Única Fonte da Verdade: O arquivo de schema define tanto a estrutura do banco de dados quanto os tipos TypeScript
• Migrações que Fazem Sentido: O sistema de migração é direto e confiável
• Flexibilidade de Banco de Dados: Posso alternar entre PostgreSQL, MySQL e SQLite sem mudar o código da aplicação

Modelagem de Dados no SaaS Boilerplate

Para o boilerplate, dediquei um tempo significativo projetando um schema Prisma que funcionasse bem para aplicações SaaS multi-tenant:

// Trecho do arquivo schema.prisma real
model Organization {
  id            String    @id @default(cuid())
  name          String
  slug          String    @unique
  imageUrl      String?
  
  users         OrganizationUser[]
  subscriptions Subscription[]
  projects      Project[]
  
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt
  deletedAt     DateTime?

O SaaS Boilerplate utiliza um modelo de dados cuidadosamente projetado para atender às necessidades de aplicações SaaS modernas. Vamos explorar as principais entidades do nosso schema do Prisma e como elas se relacionam entre si.

### Principais Entidades do SaaS Boilerplate

1. **Organization**
   - Centro do nosso sistema multi-tenant
   - Cada cliente é representado por uma organização
   - Contém informações como nome, slug e logo
   - Relaciona-se com membros, convites, chaves de API e webhooks

2. **User**
   - Representa os usuários da plataforma
   - Armazena informações de autenticação e perfil
   - Um usuário pode pertencer a múltiplas organizações

3. **Member**
   - Representa a relação entre usuários e organizações
   - Define papéis como 'owner', 'admin' ou 'member'
   - Controla permissões dentro de uma organização

4. **Customer**
   - Representa o cliente para integrações de pagamento
   - Vinculado a uma organização
   - Gerencia assinaturas e informações de faturamento

5. **Plan** e **Price**
   - Definem os planos de assinatura disponíveis
   - Gerenciam preços, intervalos de cobrança e recursos incluídos

6. **Subscription**
   - Conecta um Customer a um Price específico
   - Gerencia o status da assinatura (ativa, cancelada, etc.)
   - Controla ciclos de faturamento e quantidades

7. **ApiKey** e **Webhook**
   - Permitem integrações externas com a plataforma
   - Fornecem acesso seguro à API e notificações de eventos

## Operações de Banco de Dados com o Igniter

O SaaS Boilerplate utiliza o Igniter.js para criar procedures tipadas e seguras que acessam o banco de dados através do contexto. Veja um exemplo real de uma Procedure que verifica se um usuário pode acessar um recurso específico com base em sua assinatura:

```typescript
// Exemplo real de uma Procedure do Igniter que verifica recursos da assinatura
export const SubscriptionFeatureProcedure = igniter.procedure({
  name: "SubscriptionFeatureProcedure",
  handler: async (_, { context }) => {
    return {
      subscription: {
        canAccess: async (featureId: string): Promise<boolean> => {
          const { organization } = context;
          if (!organization) return false;
          
          // Usando o Prisma para buscar a assinatura ativa da organização
          const subscription = await context.providers.database.subscription.findFirst({
            where: {
              organizationId: organization.id,
              status: 'active'
            },
            include: {
              plan: true
            }
          });
          
          if (!subscription) return false;
          return subscription.plan.features.includes(featureId);
        }
      }
    };
  }
});

Arquitetura de Dados Multi-tenant

Uma das características mais importantes do SaaS Boilerplate é sua arquitetura multi-tenant robusta. Cada organização é completamente isolada, com seus próprios dados, usuários e recursos. Isso é implementado através de relações cuidadosamente projetadas no schema do Prisma.

Por exemplo, quando um usuário acessa a API, o contexto da organização atual é automaticamente injetado em todas as consultas ao banco de dados, garantindo que os usuários só possam acessar dados da sua própria organização.

// Exemplo de como o contexto da organização é usado para filtrar dados
async function getOrganizationUsers(organizationId: string) {
  return context.providers.database.organizationUser.findMany({
    where: {
      organizationId,
    },
    include: {
      user: {
        select: {
          id: true,
          name: true,
          email: true,
          imageUrl: true,
        },
      },
    },
    orderBy: {
      createdAt: 'desc',
    },
  });
}

Como Integrei o Prisma com o Resto da Stack

Integrei cuidadosamente o Prisma com outras partes do boilerplate:

• Integração com Igniter.js: O acesso ao banco de dados está disponível através do contexto em todos os procedimentos
• Validação com Zod: Os schemas de validação estão alinhados com os modelos do Prisma
• Suporte a Middleware: Filtragem automática baseada na organização atual
• Sistema de Seeding: Popule facilmente seu banco de dados com dados de teste durante o desenvolvimento

Otimizações de Performance que Implementei

O Prisma já é rápido, mas adicionei algumas otimizações extras:

• Estratégias Inteligentes de Consulta: Busque apenas os dados que você realmente precisa
• Pool de Conexões: Configurado para desempenho ideal sob carga
• Prevenção de Consultas N+1: Usando include e select para evitar armadilhas de desempenho
• Camada de Cache: Cache opcional com Redis para dados acessados frequentemente

Principais Entidades e Seus Relacionamentos

Vamos explorar mais detalhadamente algumas das entidades principais do nosso schema e como elas são utilizadas no SaaS Boilerplate:

Gerenciamento de Organizações e Usuários

O sistema de organizações e usuários é o núcleo do nosso SaaS Boilerplate. Uma organização pode ter múltiplos usuários, e um usuário pode pertencer a múltiplas organizações com diferentes papéis.

• Organization: Representa um cliente ou equipe usando o sistema
• User: Representa um usuário individual da plataforma
• Member: Conecta usuários a organizações com papéis específicos
• Invitation: Gerencia convites para novos membros se juntarem a uma organização

Sistema de Assinaturas e Pagamentos

O gerenciamento de assinaturas é implementado através das seguintes entidades:

• Customer: Vincula uma organização a um cliente no sistema de pagamento
• Plan: Define os diferentes planos disponíveis para assinatura
• Price: Especifica os preços e intervalos de cobrança para cada plano
• Subscription: Registra a assinatura ativa de uma organização

Integrações e API

Para permitir extensibilidade e integração com sistemas externos:

• ApiKey: Permite acesso programático à API da plataforma
• Webhook: Configura notificações para eventos específicos
• Integration e InstalledIntegration: Gerenciam integrações de terceiros

Gerenciando Mudanças no Banco de Dados

Um dos meus recursos favoritos do Prisma é o sistema de migrações. Veja meu fluxo de trabalho:

1. Faço alterações no arquivo schema.prisma
2. Executo npx prisma migrate dev --name o_que_mudei
3. Reviso o SQL gerado (sim, eu sempre verifico isso)
4. Faço commit tanto das alterações no schema quanto dos arquivos de migração

Esta abordagem me proporciona:

• Schema Versionado: Cada alteração é rastreada no Git
• Implantações Seguras em Produção: As migrações são executadas automaticamente durante a implantação
• Capacidade de Rollback: Posso reverter para versões anteriores do schema se necessário

Flexibilidade e Desacoplamento

Embora eu utilize o Prisma desde a versão 2 e o tenha escolhido pela segurança de tipos e produtividade que ele oferece, entendo que cada projeto tem suas necessidades específicas. O SaaS Boilerplate foi construído para ser flexível.

Se você preferir usar outra solução de banco de dados, é possível desacoplar o sistema do Prisma. Você pode implementar uma camada de repositório que abstrai o acesso ao banco de dados, permitindo que você troque o Prisma por qualquer outra tecnologia sem afetar o restante da aplicação.

No entanto, continuaremos mantendo e aprimorando o suporte ao Prisma no boilerplate, pois acreditamos que ele oferece a melhor combinação de produtividade e segurança para a maioria dos projetos SaaS.

Comece a Construir com Prisma Hoje

Para saber mais sobre como implementei o Prisma e como você pode aproveitá-lo em seu projeto, confira a documentação do banco de dados.

Com esta base estabelecida, você pode se concentrar na construção de seus recursos exclusivos, em vez de lutar com consultas de banco de dados e gerenciamento de schema.

Construindo com dados, Felipe