Prisma 8: use a Skill na versão certa antes de mexer em contratos e migrações

ANÁLISE EDITORIAL

Uma migração de banco pode parecer apenas mais um comando até o agente confundir a versão do projeto, escolher a origem errada do plano ou aplicar uma alteração que ainda não foi revisada. A Skill oficial prisma-8 tenta colocar um mapa na frente desse trabalho: ela identifica a tarefa, manda ler a referência correspondente e exige conferir a versão instalada antes de sugerir código. O ponto mais útil não é acelerar um comando, mas impedir que instruções de Prisma 8 sejam usadas em um projeto Prisma 7.

Este catálogo oferece uma cópia documental fixada em um commit para estudo e auditoria. Em um projeto real, a recomendação principal do próprio Prisma é obter a Skill que vem com os pacotes instalados por meio de prisma skills sync. A cópia local não atualiza a biblioteca, não conecta um banco e não executa uma migração.

O que esta Skill faz de verdade

O SKILL.md do Prisma fixado no commit é um roteador para documentos mais específicos. Se a dúvida é começar, aponta para references/quickstart.md. Se o trabalho envolve um contrato de dados, consultas, runtime, depuração ou migração, indica a referência apropriada antes de o agente escrever algo. Ele também define três verificações iniciais: confirmar que o projeto usa Prisma 8, comparar a versão do arquivo com a dependência instalada e conferir se os artefatos do contrato existem e estão atuais.

O modelo descrito pela Skill é centrado em um contrato de dados. O desenvolvedor edita o contrato, gera artefatos como contract.json e contract.d.ts e então planeja as mudanças do banco. O manual oficial dos artefatos de contrato explica por que eles são a base para as outras etapas. Isso não significa que toda diferença de esquema possa ser aplicada sem revisão: origem do plano, dados existentes, transformações e ambiente de destino continuam sendo decisões humanas.

Em 13 de outubro de 2026, a API do repositório prisma/orm registrava 47.689 estrelas. O mantenedor é a organização Prisma, o repositório declara Apache License 2.0 e esta curadoria fixa o commit 9d489d5d24b82d1a00bd0e2bca06b70081bef803. Estrelas medem interesse no repositório inteiro, não validam esta Skill, a segurança de uma migração ou a compatibilidade com sua aplicação.

Para quem serve

Ela serve a quem já trabalha em uma aplicação com @prisma/orm-postgres, @prisma/orm-sqlite ou @prisma/orm-mongo e quer que um agente consulte as instruções correspondentes àquela linha do produto. Um caso concreto é pedir ajuda para acrescentar um campo ao contrato e, antes de tocar no banco, exigir um plano de migração explicado em linguagem legível. Outro é investigar um erro de migração com o código e o contexto corretos, sem misturar respostas antigas de @prisma/client.

Não é uma Skill genérica de SQL nem uma forma de migrar automaticamente um projeto antigo. O próprio arquivo avisa que um projeto baseado em schema.prisma e @prisma/client pode estar em Prisma 7 ou anterior, caso em que estas instruções não devem ser aplicadas. Para entender a diferença entre as linhas, consulte a referência oficial do Prisma 8 e identifique a versão de cada pacote no manifesto do seu projeto.

Compatibilidade e pré-requisitos

O arquivo auditado declara metadata.library_version: 8.0.0-rc.17. Isso é uma identificação da cópia, não uma promessa de que ela corresponde à versão mais recente ou à que você usa. Antes de carregar a Skill, abra package.json e compare a versão instalada de @prisma/orm-* com a versão no frontmatter. Se forem diferentes, use a sincronização oficial de Skills do Prisma e releia a cópia gerada pelo seu próprio projeto. O mantenedor explica que a Skill acompanha os pacotes para evitar instruções defasadas.

Você também precisa de um agente que leia pastas com SKILL.md, de um projeto de teste e de acesso apenas ao banco de desenvolvimento ou a uma réplica descartável para os primeiros passos. O contrato deve estar identificado em prisma.config.ts. Se contract.json e contract.d.ts não existirem ou estiverem defasados em relação à origem, a Skill manda gerar os artefatos antes de discutir consultas ou migrações. Confirme a configuração e a conexão sem expor DATABASE_URL ao chat, ao ZIP ou a logs públicos.

Instalação recomendada

1. Se a aplicação já usa Prisma 8, confira as dependências instaladas e rode prisma skills sync conforme a documentação oficial. Essa é a instalação preferencial, porque copia a Skill da versão presente no projeto. Leia a pasta resultante antes de permitir que o agente aja.
2. Para estudar o commit desta curadoria, baixe o ZIP documental pelo cartão local separado do botão de repositório. Compare o SHA-256 do arquivo com 21ba660e1dd85543163719a9790974f9d7f657e1ecb6ccd9e2a46a8242c6eea7 antes de extrair. Abra ORIGEM.md e LICENSE.
3. Extraia os arquivos numa pasta chamada prisma-8 dentro do diretório de Skills reconhecido pelo agente. O ZIP contém o SKILL.md e as referências Markdown com a hierarquia original. Não contém scripts de upgrade, dependências ou credenciais. Para executar o fluxo completo, prefira a distribuição oficial correspondente à versão instalada.
4. Não coloque duas cópias com o mesmo nome em locais diferentes sem saber qual delas o agente carrega. A orientação do mantenedor descreve a cópia manual apenas como alternativa. Se o cliente não detectar a pasta, verifique suas regras de descoberta antes de repetir a instalação.

O botão do repositório oficial abre a origem e o histórico. O download próprio oferece o recorte auditado e imutável com checksum. Nenhum dos dois instala o servidor de banco ou executa db migrate.

Configuração antes do primeiro uso

Comece com uma tarefa que peça análise, não mutação: “Identifique a versão Prisma deste projeto, diga se esta Skill combina com ela e mostre quais arquivos precisaria ler para planejar a adição de um campo opcional”. A resposta adequada deve citar o manifesto, o frontmatter e a referência de contrato ou migrações. Se o agente partir diretamente para alterar schema.prisma ou sugerir comandos da linha antiga, interrompa o processo e confira a detecção de versão.

Defina desde o início uma fronteira para comandos que escrevem no banco. Leitura do repositório, geração de um plano e revisão do SQL proposto podem ocorrer em etapas separadas. Aplicar em desenvolvimento, homologação ou produção exige autorização específica, backup apropriado e revisão do plano contra dados reais. O guia oficial de migrações distingue planejar, revisar e aplicar; a Skill não substitui essa separação.

Primeiro uso seguro e resultado esperado

Em um projeto de laboratório compatível, peça ao agente que localize o contrato, verifique os artefatos e explique uma alteração fictícia sem executá-la. Para uma aplicação nova, a referência quickstart.md diferencia a criação da estrutura do projeto da conexão ao banco. prisma orm init prepara arquivos e dependências, mas não prova que uma conexão ou consulta funcionará. O resultado esperado do primeiro contato é um diagnóstico de versão, arquivos e próximos passos, não uma migração já aplicada.

Num segundo teste, peça que compare o estado atual do contrato com a mudança proposta e indique a origem do plano. A referência migration-model.md alerta que migration plan não assume automaticamente a migração mais nova em disco como ponto inicial. Em um projeto que já tem histórico, escolher a origem errada pode gerar um plano desde o zero ou um erro de origem desconhecida. O agente deve explicar qual referência ou hash está usando e por quê. Não alegamos que este exercício foi executado no seu banco.

Se a resposta trouxer um comando de escrita, peça antes: qual banco ele atinge, quais tabelas ou coleções muda, qual backup existe, como validar depois e qual é o plano de retorno. A referência migration-review.md trata revisão de implantação e concorrência. Uma resposta que só diz “rode migrate” sem esses elementos não satisfaz o objetivo editorial desta Skill.

Permissões e riscos

O ZIP local é texto, mas uma Skill orienta um agente que pode ter terminal, acesso ao código e credenciais de banco. O risco está nessas permissões combinadas. Use credenciais de menor privilégio para análise e teste; não dê escrita em produção apenas para experimentar um prompt. Não cole strings de conexão em mensagens nem aceite que um agente esconda decisões de migração dentro de uma sequência de comandos.

O pacote auditado exclui os scripts do repositório porque o Bastidores distribui apenas documentação permitida. Algumas referências de upgrade mencionam esses scripts, portanto não interprete a ausência deles como autorização para recriá-los ou executá-los de memória. Se você precisa atualizar uma aplicação, use o pacote oficial completo, verifique a versão instalada e leia as instruções específicas da transição. O texto desta página não é um teste de compatibilidade, benchmark ou garantia de segurança.

Erros comuns e como investigar

O agente responde como se fosse Prisma 7. Confira se a pasta carregada é a correta, se package.json realmente contém os pacotes de Prisma 8 e se a Skill sincronizada combina com essa versão. Não corrija a resposta acrescentando comandos aleatórios: sincronize e reabra o arquivo. Faltam contract.json ou contract.d.ts. Confirme o caminho do contrato em prisma.config.ts e siga a etapa contract emit descrita pela referência, primeiro num ambiente seguro.

O plano tenta recriar tudo. Investigue a origem usada pelo comando e as referências do histórico, conforme migration-model.md, antes de aplicar qualquer saída. A migração encontra divergência ou erro de hash. Registre o código estruturado e consulte references/debug.md; não apague histórico nem marque o banco como válido apenas para silenciar o erro. O ZIP local aponta para um script ausente. Isso é uma limitação deliberada do recorte documental. Para fluxos de upgrade que dependam dele, instale a Skill diretamente dos pacotes oficiais da versão do projeto.

Versão, licença e download local

Esta edição corresponde ao commit 9d489d5d24b82d1a00bd0e2bca06b70081bef803 do repositório mantido pela Prisma e ao frontmatter 8.0.0-rc.17 do arquivo principal. A redistribuição do recorte documental é coberta pela Apache License 2.0 do projeto, cujo texto integral acompanha o ZIP. Ele contém 70 arquivos Markdown da Skill, LICENSE e ORIGEM.md, sem scripts ou binários. O SHA-256 do ZIP é 21ba660e1dd85543163719a9790974f9d7f657e1ecb6ccd9e2a46a8242c6eea7. A versão e a contagem de estrelas foram consultadas em 13/10/2026; ambas podem mudar na origem.

As páginas individuais deste catálogo permanecem fora do índice e sem anúncios enquanto forem inventário modelado; a descoberta pública fica no catálogo de Skills do Bastidores. O pacote local serve para examinar o que foi curado neste commit. Para trabalho ativo, confirme a versão e a documentação atual do mantenedor.

Fontes primárias

Foram consultados o SKILL.md fixado, as referências oficiais no mesmo commit, a documentação de sincronização, a documentação dos artefatos e o guia de migrações. A interpretação e os alertas acima são editoriais; não representam uma execução de banco ou uma recomendação para aplicar mudanças em produção sem revisão.