Prisma para JavaScript (Node.js): guia completo com exemplos

Prisma é um ORM (Object-Relational Mapping) moderno para Node.js e TypeScript que transforma completamente a forma de trabalhar com bancos de dados. Diferente dos ORMs tradicionais, o Prisma oferece um modelo de dados declarativo, geração automática de um cliente com type safety e uma ferramenta poderosa para migrações. Se você está cansado de escrever consultas SQL manualmente, lidar com confusão de tipos de dados e configurações complexas de ORM, o Prisma é a solução ideal.

Por que usar Prisma? Primeiro, ele garante type safety no nível do banco de dados. Isso significa que erros relacionados a tipos de campos incorretos ou relacionamentos ausentes são detectados em tempo de compilação, não em tempo de execução. Segundo, o Prisma oferece uma API intuitiva para operações CRUD, filtragem, ordenação e agregação de dados. Terceiro, ele gera automaticamente documentação do seu esquema de dados e facilita o gerenciamento de mudanças no esquema por meio de migrações.

O Prisma suporta os principais bancos de dados relacionais: PostgreSQL, MySQL, SQLite, SQL Server e MongoDB (no modo Document). Graças à sua arquitetura, é ideal tanto para projetos pequenos quanto para aplicações enterprise. Neste artigo, vamos detalhar a instalação, os métodos principais e exemplos reais de uso do Prisma no ambiente Node.js.

Instalação

A instalação do Prisma consiste em duas etapas: instalação da CLI (Command Line Interface) e inicialização do projeto. Execute os seguintes comandos no terminal do seu projeto:

npm install prisma --save-dev
npm install @prisma/client

Após a instalação, inicialize o Prisma no projeto:

npx prisma init

Este comando cria o diretório prisma com o arquivo schema.prisma e o arquivo .env para variáveis de ambiente. No arquivo .env, informe a string de conexão com seu banco de dados. Por exemplo, para PostgreSQL:

DATABASE_URL="postgresql://usuario:senha@localhost:5432/meubanco"

Para MySQL:

DATABASE_URL="mysql://usuario:senha@localhost:3306/meubanco"

Para SQLite (banco de dados em arquivo):

DATABASE_URL="file:./dev.db"

Início rápido: exemplo mínimo funcional

Vamos criar um modelo simples de usuário e realizar operações básicas. Edite o arquivo prisma/schema.prisma:

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite" // ou "postgresql", "mysql"
  url      = env("DATABASE_URL")
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User    @relation(fields: [authorId], references: [id])
  authorId  Int
}

Agora execute a migração para criar as tabelas no banco de dados:

npx prisma migrate dev --name init

Após a migração bem-sucedida, gere o Prisma Client:

npx prisma generate

Agora crie o arquivo index.js e escreva um script simples:

// index.js
const { PrismaClient } = require('@prisma/client');

const prisma = new PrismaClient();

async function main() {
  // Criando um novo usuário
  const user = await prisma.user.create({
    data: {
      email: 'alice@exemplo.com',
      name: 'Alice',
    },
  });
  console.log('Usuário criado:', user);

  // Criando um post para o usuário
  const post = await prisma.post.create({
    data: {
      title: 'Meu primeiro post',
      content: 'Conteúdo do post',
      authorId: user.id,
    },
  });
  console.log('Post criado:', post);

  // Buscando usuário com seus posts
  const userWithPosts = await prisma.user.findUnique({
    where: { id: user.id },
    include: { posts: true },
  });
  console.log('Usuário com posts:', JSON.stringify(userWithPosts, null, 2));
}

main()
  .catch((e) => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    await prisma.$disconnect();
  });

Execute o script:

node index.js

Você verá a saída com os dados criados. Isso demonstra como o Prisma simplifica operações de banco de dados com uma API limpa e type-safe.

Métodos principais do Prisma Client

O Prisma Client oferece uma variedade de métodos para interagir com seu banco de dados. Abaixo estão os mais importantes:

create - Criar registros

Para inserir um novo registro no banco de dados:

const novoUsuario = await prisma.user.create({
  data: {
    email: 'joao@exemplo.com',
    name: 'João Silva',
  },
});

findUnique - Buscar registro único

Para buscar um registro por um campo único (como id ou email):

const usuario = await prisma.user.findUnique({
  where: { email: 'joao@exemplo.com' },
});

findMany - Buscar múltiplos registros

Para listar registros com filtros, ordenação e paginação:

const usuarios = await prisma.user.findMany({
  where: { name: { contains: 'João' } },
  orderBy: { name: 'asc' },
  take: 10,
  skip: 0,
});

update - Atualizar registros

Para atualizar um ou mais registros:

const usuarioAtualizado = await prisma.user.update({
  where: { id: 1 },
  data: { name: 'João Atualizado' },
});

delete - Excluir registros

Para excluir um registro:

const usuarioExcluido = await prisma.user.delete({
  where: { id: 1 },
});

upsert - Criar ou atualizar

Combina create e update: se o registro existir, atualiza; caso contrário, cria:

const usuario = await prisma.user.upsert({
  where: { email: 'joao@exemplo.com' },
  update: { name: 'João Atualizado' },
  create: { email: 'joao@exemplo.com', name: 'João Novo' },
});

count - Contar registros

Para contar o número de registros que correspondem a um filtro:

const totalUsuarios = await prisma.user.count();
const usuariosAtivos = await prisma.user.count({
  where: { posts: { some: { published: true } } },
});

aggregate - Agregações

Para realizar operações de agregação como soma, média, mínimo e máximo:

const agregacao = await prisma.post.aggregate({
  _avg: { id: true },
  _sum: { id: true },
  _min: { id: true },
  _max: { id: true },
  _count: { id: true },
});

groupBy - Agrupar registros

Para agrupar registros por um campo e aplicar agregações:

const postsPorAutor = await prisma.post.groupBy({
  by: ['authorId'],
  _count: { id: true },
  _avg: { id: true },
});

Relacionamentos e consultas aninhadas

O Prisma facilita o trabalho com relacionamentos entre modelos. Você pode incluir registros relacionados em uma única consulta usando a opção include ou select:

// Incluindo posts ao buscar usuário
const usuarioComPosts = await prisma.user.findUnique({
  where: { id: 1 },
  include: { posts: true },
});

// Selecionando campos específicos com relacionamentos
const usuarioSelecionado = await prisma.user.findUnique({
  where: { id: 1 },
  select: {
    email: true,
    name: true,
    posts: {
      select: { title: true, published: true },
    },
  },
});

Você também pode criar registros com relacionamentos aninhados:

// Criando usuário com posts diretamente
const usuarioComPosts = await prisma.user.create({
  data: {
    email: 'maria@exemplo.com',
    name: 'Maria',
    posts: {
      create: [
        { title: 'Post 1', content: 'Conteúdo do post 1' },
        { title: 'Post 2', content: 'Conteúdo do post 2' },
      ],
    },
  },
  include: { posts: true },
});

Migrações e gerenciamento do esquema

O Prisma oferece um sistema de migrações para gerenciar alterações no esquema do banco de dados de forma segura e versionada.

Criar uma migração

npx prisma migrate dev --name descricao_da_mudanca

Aplicar migrações em produção

npx prisma migrate deploy

Resetar o banco de dados (cuidado: apaga dados)

npx prisma migrate reset

Prisma Studio: interface gráfica

O Prisma inclui uma ferramenta visual chamada Prisma Studio, que permite visualizar e editar dados do banco de dados diretamente no navegador:

npx prisma studio

Isso abre uma interface web em http://localhost:5555 onde você pode navegar pelas tabelas, criar, editar e excluir registros visualmente.

Boas práticas e dicas

Sempre use migrações para alterar o esquema do banco em vez de modificar manualmente as tabelas.
Mantenha o Prisma Client atualizado executando npx prisma generate após cada alteração no schema.
Use variáveis de ambiente para armazenar a string de conexão do banco de dados.
Para consultas complexas, utilize raw queries quando necessário, mas prefira a API do Prisma sempre que possível.
Implemente logging para depurar consultas: const prisma = new PrismaClient({ log: ['query'] });
Considere usar extensões do Prisma para adicionar funcionalidades como soft delete, auditoria e criptografia.

Conclusão

O Prisma é uma ferramenta poderosa que simplifica drasticamente o trabalho com bancos de dados em aplicações Node.js. Com sua abordagem declarativa, type safety nativo e API intuitiva, ele se destaca como uma das melhores opções de ORM para projetos modernos. Seja você um desenvolvedor iniciante ou experiente, o Prisma pode aumentar significativamente sua produtividade e reduzir erros relacionados a banco de dados.

Comece hoje mesmo a usar o Prisma em seus projetos Node.js e experimente uma nova forma de interagir com bancos de dados!