Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
Aplicações Next.js App Router falam com o MySQL a partir de três lugares diferentes: Server Components, Server Actions e Route Handlers. Este guia conecta ao MySQL a partir dos três usando o driver mysql2 puro e um único pool de conexões compartilhado, sem nenhum ORM no meio. Como o VillageSQL é um substituto direto do MySQL, toda instrução aqui executa contra ele sem alteração.

Configurando o Banco de Dados

Crie um banco de dados dedicado e um usuário de aplicação, em vez de conectar como root:
Crie uma tabela para trabalhar:
Crie a estrutura da aplicação e instale o driver:
Guarde os detalhes de conexão em .env.local, não no código-fonte:

O Pool de Conexões

Todo lugar da aplicação que fala com o MySQL importa o mesmo pool de um único módulo, src/lib/db.ts:
Este é o mesmo padrão usado para manter em cache um cliente Prisma ou Drizzle entre hot reloads, aplicado diretamente a um pool mysql2. connectionLimit, waitForConnections e queueLimit são explicados em Pool de Conexões no MySQL; este guia se concentra no que muda quando o pool vive dentro de um processo Next.js. O cache em globalThis não é opcional no modo de desenvolvimento. Um teste nesta aplicação prova o porquê: executar npm run dev com o cache no lugar e salvar src/lib/db.ts quatro vezes seguidas deixou exatamente uma conexão nextjs_app aberta o tempo todo, verificado com:
Remover o cache em globalThis e repetir os mesmos quatro salvamentos contra um processo next dev novo elevou essa contagem para cinco. Cada reload executou novamente o nível superior do módulo, e cada execução chamou mysql.createPool() de novo sem nunca fechar o pool anterior. Edite o próprio módulo do pool para ver isso: salvar uma página que apenas o importa não o executa de novo, porque o Turbopack mantém o módulo inalterado vivo durante a recompilação. Em produção isso não acontece, porque next build compila a aplicação uma vez e next start a executa sem recarregar módulos, mas a proteção não custa nada em produção e evita um vazamento de conexões real e reproduzível em desenvolvimento.

Consultando a partir de um Server Component

src/app/page.tsx lê de notes diretamente em um Server Component, com uma consulta parametrizada:
Nunca construa a string da consulta concatenando ou interpolando entrada do usuário. O placeholder LIMIT ? acima é preenchido pelo mysql2, não por concatenação de strings, que é o que impede um valor como 20; DROP TABLE notes de fazer qualquer coisa além de falhar ao ser interpretado como número. O mysql2 retorna uma coluna TIMESTAMP do MySQL como um objeto Date do JavaScript, não como string. Com a interface Note acima tipando created_at como Date, renderizá-la diretamente como JSX ({note.created_at}) falha na verificação de tipos de npm run build antes mesmo de a aplicação executar:
Sem essa anotação de tipo, o mesmo erro aparece mais tarde e pior, como uma falha em tempo de execução em vez de um erro em tempo de build: Error: Objects are not valid as a React child (found: [object Date]). De qualquer forma, a correção é a mesma: chame .toISOString() (ou uma biblioteca de formatação) no valor onde ele é renderizado, em vez de tratá-lo como string. Compilar a aplicação com npm run build mostra que esta página não tem dependência de dados do momento da requisição (sem cookies(), sem headers(), nada marcado como dinâmico), então o Next.js a pré-renderiza como conteúdo estático no momento do build:
Isso significa que a consulta em getNotes() executa uma vez, durante next build, e o banco de dados precisa estar acessível no momento do build. A Server Action abaixo mantém o conteúdo da página atualizado revalidando-a após cada escrita, em vez de executar novamente a consulta a cada requisição.

Escrevendo com uma Server Action

src/app/actions.ts faz a inserção por meio do mesmo pool:
O formulário na página inicial passa essa função diretamente como seu action:
Enviar esse formulário por um navegador real, preenchendo “Server Action verified end to end” e clicando em Add, inseriu uma nova linha sem navegação completa de página, e a linha apareceu imediatamente na lista renderizada por causa de revalidatePath("/"). Consultar o banco de dados diretamente depois confirmou a escrita:
revalidatePath("/") invalida a renderização estática em cache da seção anterior, então a próxima requisição executa getNotes() novamente em vez de servir o snapshot do momento do build. Sem essa chamada, o cache de dados de uma página estática nunca perceberia a nova linha.

Um Route Handler JSON

Server Components e Server Actions cobrem páginas renderizadas pelo próprio Next.js. Um Route Handler é a peça que um guia focado em ORM normalmente pula, porque ele é a superfície de API HTTP pura em vez de uma página: src/app/api/notes/route.ts responde a uma requisição GET com JSON, para um cliente móvel, um webhook ou qualquer chamador que não seja o frontend do Next.js.
Executar a aplicação compilada com npm run start (porta 3000 por padrão) e requisitar essa rota retorna linhas reais de notes, não dados de exemplo, incluindo a linha que a Server Action inseriu acima:
Diferente da página inicial, essa rota lê dados do momento da requisição indiretamente (ela consulta o banco de dados a cada chamada em vez de no momento do build), então a mesma saída de build acima a marca com ƒ para dinâmica em vez de ○ para estática.

Dimensionamento do Pool de Conexões no Next.js

Um Route Handler executa uma vez por requisição recebida, e sob carga concorrente várias requisições podem estar em andamento ao mesmo tempo. O pool existe para que essas requisições compartilhem um número limitado de conexões MySQL em vez de cada requisição abrir a sua. Disparar 20 requisições concorrentes a /api/notes contra a aplicação em execução e verificar o servidor imediatamente:
mostrou apenas 4 conexões em uso, contra um pool configurado com connectionLimit: 10. Threads_connected conta todas as conexões no servidor, não só as desta aplicação, então use a consulta a information_schema.processlist de mais cedo neste guia quando precisar do número por usuário. O número exato depende de quão rápido cada consulta termina em relação ao momento em que a rajada chega, então uma consulta mais lenta ou um servidor mais ocupado mostraria uma contagem maior, até o limite configurado. O que isso confirma, de qualquer forma, é o pool enfileirando e reutilizando conexões durante a rajada em vez de abrir 20. Aumentar connectionLimit aumenta quantas requisições podem executar suas consultas em paralelo antes que as demais esperem na fila interna do pool (limitada por queueLimit, ou ilimitada se queueLimit for 0); isso não muda quantas requisições a aplicação pode aceitar, apenas quantas podem estar no meio de uma consulta contra o MySQL ao mesmo tempo. Duas coisas específicas do Next.js afetam esse número na prática:
  • Cada processo de servidor tem seu próprio pool. Uma implantação Next.js que executa várias instâncias (vários processos next start, ou várias instâncias de função serverless) multiplica connectionLimit por quantas instâncias estiverem em execução. Dimensione connectionLimit e o max_connections do MySQL juntos, não connectionLimit sozinho.
  • O modo de desenvolvimento pode multiplicar pools dentro de um único processo, como mostrado na seção do pool de conexões acima, se o pool não estiver em cache em globalThis. Isso não acontece em um build de produção, mas vale a pena verificar durante o desenvolvimento, porque o sintoma (o MySQL reportando muito mais conexões abertas do que a aplicação deveria precisar) é idêntico a um problema de dimensionamento em produção.

Escolhendo um ORM em Vez Disso

Este guia usa o mysql2 diretamente porque um pool de conexões puro é a peça que toda integração entre Next.js e MySQL compartilha, independentemente do que fica em cima dele. Se a aplicação se beneficiaria de tipos gerados, migrações ou um query builder, consulte Next.js e Prisma com MySQL ou Next.js e Drizzle com MySQL para a configuração específica do MySQL, e Usando MySQL com ORMs para as configurações que importam em ORMs de forma geral.

Perguntas Frequentes

Por que renderizar note.created_at falha em vez de simplesmente imprimir como texto?

O mysql2 decodifica uma coluna TIMESTAMP ou DATETIME do MySQL em um objeto Date do JavaScript, e nem o tipo ReactNode do TypeScript nem o próprio React conseguem renderizar um diretamente como JSX. Com a coluna tipada como Date, npm run build captura {note.created_at} na verificação de tipos com error TS2322: Type 'Date' is not assignable to type 'ReactNode'. Sem esse tipo, o mesmo erro chega ao tempo de execução e lança Error: Objects are not valid as a React child (found: [object Date]). Chame .toISOString(), .toLocaleString() ou uma biblioteca de formatação no valor antes de renderizá-lo.

Preciso de um pool de conexões se espero apenas alguns usuários?

Sim. Mesmo com tráfego leve, o Next.js pode executar várias requisições concorrentemente (um carregamento de página que também chama um Route Handler, duas abas do navegador, um bot rastreando o site), e cada conexão MySQL é uma thread real no servidor. Um pool com um connectionLimit pequeno, dez é um padrão razoável para uma aplicação pequena, não custa nada quando ocioso e impede que uma rajada de requisições concorrentes abra uma conexão cada.

Posso chamar uma Server Action a partir de um Route Handler, ou o contrário?

Um Route Handler pode chamar a mesma função que uma Server Action chama, já que ambos são apenas funções assíncronas que usam o pool. O que difere é a convenção de chamada: uma Server Action é invocada por um <form action> ou pelo useActionState do React, e um Route Handler é invocado por uma requisição HTTP. Compartilhe a lógica de banco de dados em uma função comum e chame-a dos dois lugares, em vez de fazer um chamar o outro diretamente.

Por que a página inicial é estática mas a rota de API não é?

O Next.js decide isso por rota, com base em se a rota lê dados do momento da requisição. O src/app/page.tsx deste guia não chama nenhuma API de tempo de execução como cookies() ou headers(), então next build o pré-renderiza uma vez e serve esse snapshot até que revalidatePath o invalide. O Route Handler deste guia não tem esse cache aplicado, então ele consulta o banco de dados a cada requisição.

Solução de Problemas

Veja também