Prisma Upgrade v7

ANÁLISE EDITORIAL

Prisma Upgrade v7 é uma Skill oficial para migrar projetos do Prisma ORM 6 para o Prisma ORM 7. Ela organiza as mudanças de maior impacto: novo gerador de cliente, caminho de saída obrigatório, adaptadores de driver para bancos SQL, configuração em prisma.config.ts, carregamento explícito de variáveis, suporte a ESM e recursos removidos.

A versão auditada está no repositório prisma/skills, commit 808913c1dac11dc425631c2454f7fcb2d5ade5ca. O arquivo declara Prisma 7.6.0 e licença MIT. O repositório tinha 53 estrelas na consulta de 16 de agosto de 2026.

O download local contém SKILL.md, sete referências Markdown, LICENSE e ORIGEM.md. Nenhum pacote npm foi instalado, nenhum comando Prisma foi executado e nenhum banco foi acessado. Não há runtime, dependência, segredo, conexão ou credencial.

Imagem editorial exclusiva do Bastidores da IA. Não é captura do Prisma, painel de banco nem evidência de migração executada.

O que muda na migração

A Skill trata a atualização como mudança arquitetural, não como simples troca de número no package.json. O gerador prisma-client passa a usar um caminho explícito de saída. As importações deixam de depender apenas do pacote tradicional e apontam para o cliente gerado dentro do projeto. Em bancos SQL, o cliente precisa de um adaptador de driver.

A configuração de schema, migrations e datasource passa para prisma.config.ts. Variáveis de ambiente não são carregadas implicitamente da mesma forma, por isso a Skill orienta um carregamento explícito. Projetos ESM recebem o caminho principal, mas existe uma opção de formato CommonJS quando a aplicação ainda não pode migrar todo o ecossistema.

Também há substituições de API. O helper Prisma.validator() cede espaço ao operador satisfies do TypeScript. Middleware baseado em $use() deve ser revisto em direção a Client Extensions. O recurso de métricas citado como preview não segue no mesmo formato.

O bloqueio para MongoDB

O alerta mais valioso do arquivo é direto: esse guia não se aplica a projetos MongoDB. A Skill afirma que o Prisma 7 não oferece o conector MongoDB no caminho descrito e orienta permanecer na linha 6.x ou avaliar Prisma Next por meio de outra Skill.

Ignorar essa verificação pode levar uma equipe a instalar adaptadores SQL em um projeto incompatível, modificar imports e configuração e só depois descobrir que o provedor não possui rota de migração equivalente. O primeiro gate deve ler provider no schema e interromper o trabalho quando for mongodb.

Para quem serve

A Skill serve para equipes com Prisma ORM 6 que precisam avaliar ou executar uma atualização controlada. É útil quando surgem erros de importação, exigência de adaptador, dúvidas sobre ESM, mudança de geração ou carregamento de DATABASE_URL.

Ela não deve ser usada como autorização para atualizar produção, aplicar migration ou alterar banco. Uma migração de ORM pode modificar dependências, geração de tipos, pool de conexões, comportamento de transações e processo de deploy. Cada uma dessas áreas precisa de testes e rollback próprios.

Pré-requisitos que precisam ser confirmados

O arquivo declara Node.js 20.19.0 ou superior e TypeScript 5.4.0 ou superior. A aplicação também precisa identificar o banco, o driver, o modo de execução e o sistema de módulos. Projetos serverless, edge, processos longos e aplicações com pool externo podem escolher adaptadores diferentes.

Antes de mudar qualquer arquivo, registre as versões de prisma, @prisma/client, Node.js, TypeScript e driver. Preserve schema.prisma, migrations, lockfile e configuração de deploy. Um backup de banco sem teste de restauração é apenas uma esperança, não um rollback comprovado.

A Skill contém exemplos para PostgreSQL, MySQL, SQLite, Prisma Postgres, Neon e SQL Server em suas referências. Esses exemplos usam variáveis, mas não devem receber valores reais dentro do prompt. Conexões e segredos ficam no gerenciador apropriado do ambiente.

Instalação e leitura recomendadas

Abra o diretório oficial fixado no commit e compare o SKILL.md original. Depois leia primeiro schema-changes.md e driver-adapters.md, como a própria Skill orienta.

Instalar por um catálogo compatível é possível, mas o caminho mais controlado é copiar apenas a pasta fixada para um projeto de teste. Confirme que o cliente encontra as referências sem executar os comandos listados. O ZIP do Bastidores é documental e pode ser lido sem instalar dependências.

Fluxo de migração seguro

1. Crie branch e ambiente de teste isolados.
2. Registre versões, banco, provider, runtime e formato de módulos.
3. Interrompa se o provider for MongoDB.
4. Atualize dependências e lockfile sem aplicar mudanças em produção.
5. Defina gerador, caminho de saída e formato de módulos.
6. Crie prisma.config.ts e carregue variáveis explicitamente.
7. Escolha o adaptador compatível com banco e ambiente.
8. Atualize imports e instanciação do cliente.
9. Gere o cliente e execute testes de tipo, unidade e integração.
10. Compare consultas, pool, transações, erros e desempenho.
11. Teste migration e rollback com uma cópia representativa.
12. Promova em etapas e monitore conexões e falhas.

O problema dos adaptadores

O adaptador conecta o Prisma Client ao driver real. Isso traz diferenças que antes podiam ficar escondidas pelo motor: tempo de conexão, certificados, tamanho do pool, tratamento de timeout e opções específicas do driver. Uma aplicação que funcionava com valores implícitos pode precisar de configuração explícita.

A Skill inclui um exemplo que permite desativar rejeição de certificado para preservar um comportamento antigo. Esse recurso não deve virar correção padrão. Em produção, a opção pode enfraquecer a verificação TLS. O caminho preferível é configurar a cadeia de certificados corretamente e limitar qualquer exceção a um ambiente controlado.

Resultado esperado

Uma boa saída começa com um inventário e termina com evidências. O projeto deve gerar cliente, compilar e executar os testes que atravessam consultas, relações, transações e erros. O deploy precisa carregar a configuração e as variáveis no ambiente real, sem depender de comportamento implícito da máquina do desenvolvedor.

A equipe também deve registrar o que foi removido, substituído ou adiado. Se middleware, métricas ou flags antigas ainda aparecem no código ou no pipeline, a migração não terminou. Se uma parte não foi testada, o relatório deve declarar a lacuna.

Cenário prático de migração

Em um serviço Node.js que atende pedidos, comece criando uma branch exclusiva e registrando as versões atuais de Node, Prisma, driver e banco. Rode a suíte existente antes de editar dependências para estabelecer a linha de base. Em seguida, atualize os arquivos de configuração e geração de cliente em etapas pequenas, mantendo cada erro associado a uma única mudança. Se uma consulta crítica usa transação, extensão ou SQL bruto, marque-a para revisão específica em vez de presumir compatibilidade.

O primeiro teste deve usar dados descartáveis e cobrir criação, consulta, atualização, exclusão e rollback. Depois valide paginação, filtros nulos, campos opcionais e conversões de data, porque diferenças de runtime podem aparecer longe da instalação. Meça também o tempo das consultas importantes e compare com a linha de base. Uma migração que compila, mas muda cardinalidade ou desempenho, ainda não está concluída.

Antes do deploy, confira se o artefato contém o cliente gerado esperado, se variáveis de conexão não foram incorporadas ao pacote e se o procedimento de reversão realmente recupera aplicação e esquema compatíveis. O agente pode organizar a sequência e destacar mudanças documentadas. A equipe continua responsável por testar o banco real, aprovar a janela e decidir quando qualquer migração de dados pode ocorrer.

Registre o resultado de cada etapa em uma checklist curta, incluindo comando, ambiente, evidência e responsável. Assim, uma falha posterior pode ser ligada à mudança correta sem depender da memória de quem realizou a atualização.

Riscos e erros comuns

• Atualizar só os pacotes: imports, gerador, adaptador e configuração permanecem incompatíveis.
• Executar em MongoDB: o guia padrão não se aplica.
• Esquecer o cliente gerado: build local funciona, mas o artefato de deploy não encontra o caminho.
• Carregar ambiente de forma implícita: CI e produção recebem DATABASE_URL vazia.
• Usar adaptador inadequado: pool e protocolo não combinam com o runtime.
• Desabilitar TLS para passar no teste: corrige sintoma e cria risco.
• Aplicar migrations sem restauração testada: rollback vira improviso.
• Confundir compilação com equivalência: consultas e transações ainda podem mudar de comportamento.

Versão, licença e download local

O commit auditado é 808913c1dac11dc425631c2454f7fcb2d5ade5ca, com versão 7.6.0 declarada na Skill. O repositório usa licença MIT, preservada no pacote.

O ZIP local tem SHA-256 d19655c3c26c4306bcab446b4d3cc185d219bffbcadcb6729316a4cd3cf53e23, dez arquivos textuais e nenhuma dependência. Ele não executa npm install, prisma generate ou migrations.

Limite final

Prisma Upgrade v7 é um mapa de migração, não uma garantia de compatibilidade. Dependências, drivers e plataformas podem mudar depois do commit auditado. Consulte a documentação oficial de upgrade antes de implementar.

A atualização só está concluída quando o comportamento foi comparado em ambiente representativo e existe caminho de recuperação. Mantenha banco, credenciais, deploy e produção sob aprovação humana.

Fontes primárias

• Diretório oficial no commit auditado
• SKILL.md oficial
• Licença MIT
• Prisma Docs, upgrade para v7
• Prisma Docs, drivers e adaptadores