VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
mysql2, cobrindo schema, migrações, leituras a partir de um Server Component e escritas a partir de uma Server Action. Ele pressupõe uma aplicação existente criada com create-next-app --src-dir, que configura o alias de importação @/* usado nos exemplos de código.
Instale o Drizzle e o Driver MySQL
O Drizzle precisa do drivermysql2 para falar com o MySQL, além do drizzle-kit para gerar e executar migrações:
drizzle-kit evolui rapidamente e já publicou tags de pré-lançamento (beta, rc) em dist-tags ao lado de latest. Verifique npm view drizzle-orm dist-tags e npm view drizzle-kit dist-tags antes de instalar para confirmar que latest aponta de fato para uma versão estável, e não para um release candidate.
Defina a string de conexão em .env:
Crie o Usuário do Banco de Dados
Crie um banco de dados dedicado e um usuário restrito a ele, em vez de conectar a aplicação comoroot:
'localhost', independentemente de quais concessões baseadas em IP existam; um usuário criado apenas como 'drizzle_app'@'127.0.0.1' não consegue se autenticar pelo socket. Uma conexão TCP para 127.0.0.1 é comparada por busca de DNS reverso, então se ela também satisfaz uma concessão de 'localhost' depende de como o servidor resolve 127.0.0.1, não de uma regra fixa do MySQL. Conceda acesso ao host que sua aplicação realmente usa, e não conte com 127.0.0.1 e localhost serem intercambiáveis.
Defina o Schema
O schema MySQL do Drizzle usa funções dedrizzle-orm/mysql-core para descrever cada coluna:
src/db/schema.ts
varchar exige um length explícito. O MySQL armazena VARCHAR com um comprimento máximo embutido no tipo da coluna, diferente do PostgreSQL, então o Drizzle não tem um padrão a que recorrer e precisa do valor de antemão.
Configure o drizzle-kit
Odrizzle-kit lê um arquivo de configuração para saber onde o schema está e como alcançar o banco de dados:
drizzle.config.ts
drizzle-kit lê o .env por conta própria antes de o seu arquivo de configuração executar, então process.env.DATABASE_URL já está preenchido aqui sem necessidade de importar o dotenv. Isso é específico do drizzle-kit: um script Node ou tsx comum não tem esse carregador embutido, como mostra o script de verificação mais adiante neste guia.
Adicione os scripts de migração ao package.json:
package.json
Gere e Execute a Migração
drizzle-kit generate compara o arquivo de schema com a última migração gerada e escreve um novo arquivo SQL:
drizzle-kit imprime os caminhos da configuração e do schema em forma absoluta; /path/to/your-app acima representa o diretório do seu projeto. O nome do arquivo gerado inclui um sufixo aleatório de duas palavras, então o seu será diferente; apenas o prefixo numérico (0000) tem significado para a ordenação. Executar db:generate novamente sem mudança no schema reporta No schema changes, nothing to migrate em vez de escrever um segundo arquivo. A migração em si é SQL puro:
drizzle/0000_premium_tiger_shark.sql
drizzle-kit migrate cria uma tabela __drizzle_migrations na primeira vez que executa, para registrar quais arquivos de migração já foram aplicados. Confirme que as duas tabelas existem:
Crie o Cliente do Banco de Dados
O drivermysql2 conecta por meio de um pool, e o Drizzle envolve esse pool:
src/db/index.ts
mode: "default" é específica do driver mysql2 e não tem equivalente nos drivers PostgreSQL ou SQLite do Drizzle. Omiti-la é um erro de tipo, não um padrão silencioso.
Leia Posts em um Server Component
Um Server Component pode chamardb.select() diretamente durante a renderização, sem nenhuma rota de API no meio:
src/app/page.tsx
Insira Posts com uma Server Action
Uma Server Action executa no servidor e pode ser passada diretamente para a propaction de um formulário:
src/app/actions.ts
revalidatePath("/") é necessário mesmo em uma rota que renderiza a cada requisição. Sem ele, não há garantia de que a resposta de uma Server Action inclua uma cópia atualizada da página de onde ela foi chamada.
A Armadilha da Renderização Estática
npm run build compila a aplicação, mas também decide, por rota, se uma página pode ser pré-renderizada uma única vez no momento do build ou se precisa ser renderizada a cada requisição. Um Server Component que lê o banco de dados sem nenhuma outra API dinâmica na mesma rota (sem cookies(), sem headers(), sem searchParams) não dá ao Next.js nada que force a renderização por requisição, então ele pré-renderiza a página uma vez durante o build e serve esse mesmo HTML a todos os visitantes depois.
Isso foi reproduzível: remover export const dynamic = "force-dynamic"; de page.tsx e refazer o build produziu uma rota marcada como estática:
npm run start. A página continuou servindo a contagem de linhas e o conteúdo capturados no momento do build. Adicionar export const dynamic = "force-dynamic"; a page.tsx e refazer o build mudou a rota para dinâmica:
export const dynamic = "force-dynamic";, ou de outra API do Next.js (como ler cookies()) que tenha o mesmo efeito de forçar a renderização por requisição.
Verifique o Caminho de Escrita Independentemente do ORM
Um script que insere por meio do Drizzle e só verifica o valor de retorno do próprio Drizzle não prova que a linha chegou ao banco de dados; ele prova que o driver retornou sem lançar exceção. Verifique com uma consulta separada:src/db/verify-insert.ts
tsx, que executa TypeScript diretamente:
import "dotenv/config" no topo do script é obrigatório aqui. O Next.js carrega o .env para a aplicação automaticamente, mas um script independente executado com tsx é um processo Node comum, sem nenhuma ligação com o framework, e o próprio Node não lê arquivos .env.
Depois confirme que a linha existe com uma consulta que nunca passou pela aplicação:
Perguntas Frequentes
Isto funciona da mesma forma com o VillageSQL e com o MySQL?
Sim. O dialeto MySQL do Drizzle e o drivermysql2 falam o protocolo de rede padrão do MySQL, e o VillageSQL é um substituto direto do MySQL com o mesmo protocolo e as mesmas ferramentas de cliente. Nada no código de schema, migração ou consulta acima é específico de uma versão do MySQL.
Devo usar drizzle-kit generate e migrate, ou drizzle-kit push?
generate mais migrate escreve um arquivo de migração SQL que você pode revisar e commitar antes que ele seja executado contra um banco de dados, que é o que este guia usa. drizzle-kit push compara o arquivo de schema com o banco de dados ativo e aplica a diferença diretamente, sem arquivo de migração. push é mais rápido para prototipagem inicial, mas não deixa registro do que mudou ou quando, e não substitui arquivos de migração depois que outros desenvolvedores ou ambientes dependem do schema.
Por que a pasta de migração tem uma tabela chamada __drizzle_migrations?
drizzle-kit migrate cria essa tabela na primeira execução para registrar, por hash, quais arquivos de migração ele já aplicou. É assim que migrate sabe pular uma migração que já foi executada em vez de aplicá-la duas vezes.
Posso chamar db.insert() diretamente de um Server Component em vez de uma Server Action?
Um Server Component só executa durante a renderização; não há requisição do navegador para disparar uma escrita em resposta a uma ação do usuário. Um caminho de escrita precisa de uma Server Action, de um Route Handler ou de código no lado do cliente chamando uma rota de API.
Solução de Problemas
Veja também
- Next.js e Prisma com MySQL — a mesma aplicação construída com Prisma em vez de Drizzle
- Next.js com MySQL — configuração de conexão, Server Actions e padrões de Route Handler sem nenhum ORM
- Usando MySQL com ORMs: Django, Rails e Prisma — configurando opções específicas do MySQL em ORMs além do Drizzle
- Pool de Conexões no MySQL — como o pool de conexões que o
mysql2cria se encaixa nos limites de conexão do MySQL