VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
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:.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:
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:
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:
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:
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:
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:
action:
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.
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:
ƒ 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:
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) multiplicaconnectionLimitpor quantas instâncias estiverem em execução. DimensioneconnectionLimite omax_connectionsdo MySQL juntos, nãoconnectionLimitsozinho. - 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 omysql2 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 umconnectionLimit 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. Osrc/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
- Next.js e Prisma com MySQL — a mesma aplicação construída com Prisma em vez de um driver puro
- Next.js e Drizzle com MySQL — a mesma aplicação construída com Drizzle em vez de um driver puro
- Pool de Conexões no MySQL — como
connectionLimit,waitForConnectionsequeueLimitfuncionam, independentemente de qualquer framework - Usando MySQL com ORMs — as configurações que importam quando um ORM fica entre a aplicação e o MySQL