VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
Crie o banco de dados
O Prisma precisa de dois bancos de dados: o que sua aplicação usa, e um segundo banco “shadow” que ele usa internamente para calcular migrações. Crie os dois, e um usuário dedicado com direitos sobre cada um:CREATE/DROP em *.* para que o Prisma possa criar um banco shadow por conta própria, mantém o raio de dano de uma senha vazada em dois bancos de dados em vez do servidor inteiro.
Crie a estrutura da aplicação
latest do npm para prisma aponta para um release candidate da 8.0: bom para experimentar, mas o padrão errado para um guia que precisa continuar funcionando.
Inicialize o Prisma
prisma init executa por padrão uma etapa de postinstall que cria no seu repositório skills de agente para Claude Code, Cursor e Windsurf (.claude/, .windsurf/, .agents/, mais um skills-lock.json). --no-skills pula essa etapa. É um recurso genuinamente útil se você usa um agente de codificação com IA junto com o Prisma, só não faz parte do escopo deste guia.
Isso cria prisma/schema.prisma, um arquivo .env e prisma7.config.ts (o nome do arquivo de configuração tem sufixo de versão no Prisma 7). Defina as strings de conexão:
.env
schema.prisma. A partir do Prisma 7, as URLs de conexão, incluindo a URL do banco shadow, ficam em prisma7.config.ts, não no arquivo de schema:
prisma7.config.ts
schema.prisma mantém o bloco generator que o prisma init criou e agora só declara o provider no datasource, sem URL de conexão:
prisma/schema.prisma
Execute a migração
prisma/migrations/<timestamp>_init/migration.sql e chama prisma generate para você. Confirme que a tabela existe:
Conecte com um driver adapter
O cliente gerado pelo Prisma 7 não conecta mais por conta própria:new PrismaClient() sem argumentos agora falha na verificação de tipos. Você passa a ele um driver adapter, um pacote por banco de dados:
@prisma/adapter-mariadb é o adapter tanto para MariaDB quanto para MySQL: o protocolo de rede é compartilhado, então ele funciona contra o VillageSQL da mesma forma que funciona contra o MySQL padrão. Configure um singleton para que o hot reload do modo de desenvolvimento do Next.js não abra um novo pool de conexões a cada salvamento de arquivo:
src/lib/prisma.ts
A Primeira Conexão a uma Conta Nova
O MySQL 8 e o VillageSQL criam contas com o plugincaching_sha2_password. Na primeira vez que uma determinada conta se autentica, o cliente precisa completar uma troca de chaves RSA; depois disso o servidor armazena o resultado em cache e as conexões seguintes tomam um caminho mais rápido que a dispensa. O @prisma/adapter-mariadb se recusa a fazer essa troca em uma conexão não criptografada, então em um servidor que nunca autenticou essa conta, o build falha:
active=0 idle=0 faz parecer que o servidor está inacessível. O erro subjacente do driver é mais específico:
.env
asyncmy, e ela é intermitente pelo mesmo motivo: depois que qualquer cliente completa uma autenticação completa para a conta, incluindo a CLI mysql, o resultado em cache esconde o problema até que o cache seja limpo por FLUSH PRIVILEGES ou por uma reinicialização do servidor.
O caminho de importação do cliente gerado tem duas peculiaridades. Ele não tem index.ts, então você importa @/generated/prisma/client (o arquivo), não @/generated/prisma (o diretório). E toda exportação nesse arquivo é tipada com @ts-nocheck, já que é código gerado que você deve importar, não ler.
Leia e escreva a partir de um Server Component
src/app/page.tsx
prisma.post.findMany() executa como um Server Component, então a lista é renderizada com os dados já no HTML, sem busca no lado do cliente. O formulário envia para uma Server Action ("use server"), que escreve por meio do mesmo cliente Prisma e chama revalidatePath("/") para que o novo post apareça sem atualização no lado do cliente.
Executar npm run build neste ponto realmente consulta o banco de dados: como a página inicial não usa APIs dinâmicas, o Next.js a pré-renderiza como conteúdo estático no momento do build, o que significa que findMany() executa durante o build, não só no momento da requisição. Se seu banco de dados não está acessível durante npm run build, o build falha ali, então um pipeline de CI para esta aplicação precisa de um banco de dados acessível no momento do build, não só em tempo de execução.
Perguntas Frequentes
Preciso do banco shadow em produção?
Não.prisma migrate dev o usa para detectar divergência de schema enquanto você desenvolve. Em produção, use prisma migrate deploy, que aplica os arquivos de migração existentes sem tocar em nenhum banco shadow.
Por que meu script independente falha com “Cannot read properties of undefined (reading ‘prepareCacheLength’)”?
process.env.DATABASE_URL é undefined no ambiente desse script. O Next.js carrega o .env automaticamente para next dev e next build, mas um script node ou tsx comum não. Adicione import "dotenv/config" no topo do script.
Posso usar o equivalente MySQL de @prisma/adapter-pg em vez disso?
Não existe um nome de adapter específico para MySQL. @prisma/adapter-mariadb é o que o Prisma fornece tanto para MariaDB quanto para MySQL, incluindo o VillageSQL.
Solução de Problemas
Veja também
- Next.js e Drizzle com MySQL — a mesma aplicação construída com um ORM mais leve e orientado a SQL em vez do Prisma
- Next.js com MySQL — configuração de conexão, Server Actions e padrões de Route Handler sem nenhum ORM
- Usando MySQL com ORMs — as configurações que importam em todo ORM, não só no Prisma
- Pool de conexões — como o tamanho do pool de um driver adapter interage com sua contagem de processos