> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js e Drizzle com MySQL

> Como conectar uma aplicação Next.js App Router ao MySQL usando o Drizzle ORM e o driver mysql2: definição de schema, migrações com drizzle-kit, Server Components, Server Actions e a armadilha da renderização estática que serve linhas desatualizadas do banco de dados.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

O Drizzle ORM é um query builder em TypeScript que gera migrações SQL a partir de um arquivo de schema e oferece uma API de consulta tipada, sem uma linguagem de consulta intermediária própria. Este guia conecta uma aplicação Next.js App Router ao MySQL por meio do Drizzle e do driver `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 driver `mysql2` para falar com o MySQL, além do `drizzle-kit` para gerar e executar migrações:

```bash theme={null}
npm install drizzle-orm mysql2
npm install -D drizzle-kit tsx dotenv
```

O `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`:

```bash theme={null}
DATABASE_URL="mysql://drizzle_app:your_password@127.0.0.1:3306/your_database"
```

## 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 como `root`:

```sql theme={null}
CREATE DATABASE drizzle_guide;
CREATE USER 'drizzle_app'@'127.0.0.1' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON drizzle_guide.* TO 'drizzle_app'@'127.0.0.1';
```

Uma conexão pelo socket Unix é sempre comparada com o host `'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 de `drizzle-orm/mysql-core` para descrever cada coluna:

```typescript src/db/schema.ts theme={null}
import { int, mysqlTable, text, timestamp, varchar } from "drizzle-orm/mysql-core";

export const posts = mysqlTable("posts", {
  id: int("id").autoincrement().primaryKey(),
  title: varchar("title", { length: 255 }).notNull(),
  body: text("body").notNull(),
  createdAt: timestamp("created_at").defaultNow().notNull(),
});
```

`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

O `drizzle-kit` lê um arquivo de configuração para saber onde o schema está e como alcançar o banco de dados:

```typescript drizzle.config.ts theme={null}
import { defineConfig } from "drizzle-kit";

if (!process.env.DATABASE_URL) {
  throw new Error("DATABASE_URL is not set");
}

export default defineConfig({
  out: "./drizzle",
  schema: "./src/db/schema.ts",
  dialect: "mysql",
  dbCredentials: {
    url: process.env.DATABASE_URL,
  },
});
```

O `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`:

```json package.json theme={null}
{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate"
  }
}
```

## 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:

```bash theme={null}
npm run db:generate
```

```
No config path provided, using default 'drizzle.config.ts'
Reading config file '/path/to/your-app/drizzle.config.ts'
Reading schema files:
/path/to/your-app/src/db/schema.ts

1 tables
posts 4 columns 0 indexes 0 fks

[✓] Your SQL migration file ➜ drizzle/0000_premium_tiger_shark.sql 🚀
```

O `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:

```sql drizzle/0000_premium_tiger_shark.sql theme={null}
CREATE TABLE `posts` (
	`id` int AUTO_INCREMENT NOT NULL,
	`title` varchar(255) NOT NULL,
	`body` text NOT NULL,
	`created_at` timestamp NOT NULL DEFAULT (now()),
	CONSTRAINT `posts_id` PRIMARY KEY(`id`)
);
```

Aplique-a:

```bash theme={null}
npm run db:migrate
```

`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:

```bash theme={null}
mysql -h 127.0.0.1 -P 3306 -u drizzle_app -p drizzle_guide -e "SHOW TABLES;"
```

```
Tables_in_drizzle_guide
__drizzle_migrations
posts
```

## Crie o Cliente do Banco de Dados

O driver `mysql2` conecta por meio de um pool, e o Drizzle envolve esse pool:

```typescript src/db/index.ts theme={null}
import { drizzle } from "drizzle-orm/mysql2";
import mysql from "mysql2/promise";
import * as schema from "./schema";

if (!process.env.DATABASE_URL) {
  throw new Error("DATABASE_URL is not set");
}

const poolConnection = mysql.createPool(process.env.DATABASE_URL);

export const db = drizzle(poolConnection, { schema, mode: "default" });
```

A opção `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 chamar `db.select()` diretamente durante a renderização, sem nenhuma rota de API no meio:

```typescript src/app/page.tsx theme={null}
import { db } from "@/db";
import { posts } from "@/db/schema";
import { desc } from "drizzle-orm";
import { createPost } from "./actions";

export const dynamic = "force-dynamic";

export default async function Home() {
  const allPosts = await db.select().from(posts).orderBy(desc(posts.createdAt));

  return (
    <main>
      <h1>Posts</h1>
      <form action={createPost}>
        <div>
          <label htmlFor="title">Title</label>
          <input id="title" name="title" type="text" required />
        </div>
        <div>
          <label htmlFor="body">Body</label>
          <textarea id="body" name="body" required />
        </div>
        <button type="submit">Create post</button>
      </form>
      <ul>
        {allPosts.map((post) => (
          <li key={post.id}>
            <strong>{post.title}</strong>
            <p>{post.body}</p>
            <small>{post.createdAt.toISOString()}</small>
          </li>
        ))}
      </ul>
    </main>
  );
}
```

## Insira Posts com uma Server Action

Uma Server Action executa no servidor e pode ser passada diretamente para a prop `action` de um formulário:

```typescript src/app/actions.ts theme={null}
"use server";

import { revalidatePath } from "next/cache";
import { db } from "@/db";
import { posts } from "@/db/schema";

export async function createPost(formData: FormData) {
  const title = formData.get("title");
  const body = formData.get("body");

  if (typeof title !== "string" || title.trim() === "") {
    throw new Error("Title is required");
  }
  if (typeof body !== "string" || body.trim() === "") {
    throw new Error("Body is required");
  }

  await db.insert(posts).values({ title, body });

  revalidatePath("/");
}
```

`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:

```
Route (app)
┌ ○ /
└ ○ /_not-found

○  (Static)  prerendered as static content
```

Uma linha inserida diretamente no banco de dados depois desse build não apareceu quando a aplicação compilada foi iniciada com `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:

```
Route (app)
┌ ƒ /
└ ○ /_not-found

ƒ  (Dynamic)  server-rendered on demand
```

Depois dessa mudança, uma linha inserida após o build apareceu imediatamente na requisição seguinte, sem necessidade de refazer o build. Qualquer página que lê do banco de dados e precisa refletir escritas feitas depois do build precisa de `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:

```typescript src/db/verify-insert.ts theme={null}
import "dotenv/config";
import { db } from "./index";
import { posts } from "./schema";

async function main() {
  const [inserted] = await db.insert(posts).values({
    title: "Verification post",
    body: "Inserted by verify-insert.ts to confirm the write path works.",
  });

  console.log("Insert result:", inserted);
  process.exit(0);
}

main();
```

Execute-o com `tsx`, que executa TypeScript diretamente:

```bash theme={null}
npx tsx src/db/verify-insert.ts
```

```
Insert result: ResultSetHeader {
  fieldCount: 0,
  affectedRows: 1,
  insertId: 1,
  info: '',
  serverStatus: 2,
  warningStatus: 0,
  changedRows: 0
}
```

O `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:

```bash theme={null}
mysql -h 127.0.0.1 -P 3306 -u drizzle_app -p drizzle_guide -e "SELECT id, title, body, created_at FROM posts;"
```

```
id	title	body	created_at
1	Verification post	Inserted by verify-insert.ts to confirm the write path works.	2026-08-28 11:59:54
```

## Perguntas Frequentes

#### Isto funciona da mesma forma com o VillageSQL e com o MySQL?

Sim. O dialeto MySQL do Drizzle e o driver `mysql2` 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

| Problema | Solução |
| :- | :- |
| `Access denied for user 'drizzle_app'@'localhost' (using password: YES)` | A senha em `DATABASE_URL` está errada. O host exibido no erro pode aparecer como `localhost` mesmo quando a conexão foi feita para `127.0.0.1`; isso não significa que a parte de host da conta seja o problema. Verifique a senha primeiro. |
| `ERROR 1146 (42S02): Table 'drizzle_guide.posts' doesn't exist` | A migração nunca foi executada contra este banco de dados. Execute `npm run db:migrate`. |
| Uma linha inserida depois de `npm run build` não aparece na página | A rota foi pré-renderizada no momento do build. Adicione `export const dynamic = "force-dynamic";` à página e refaça o build. |
| `DATABASE_URL is not set` ao executar `drizzle-kit generate` ou `migrate` | O `.env` está faltando, ou o comando foi executado de um diretório diferente da raiz do projeto, então o `drizzle-kit` nunca o encontrou. |
| Erro de tipo na opção `mode` ao chamar `drizzle()` | O driver `mysql2` exige `mode: "default"` (ou `"planetscale"` para comportamento específico do PlanetScale); essa opção não existe nos drivers PostgreSQL ou SQLite do Drizzle. |

## Veja também

* [Next.js e Prisma com MySQL](https://villagesql.com/docs/pt-BR/guides/mysql-with-prisma.md) — a mesma aplicação construída com Prisma em vez de Drizzle
* [Next.js com MySQL](https://villagesql.com/docs/pt-BR/guides/nextjs-mysql.md) — configuração de conexão, Server Actions e padrões de Route Handler sem nenhum ORM
* [Usando MySQL com ORMs: Django, Rails e Prisma](https://villagesql.com/docs/pt-BR/guides/mysql-with-orms.md) — configurando opções específicas do MySQL em ORMs além do Drizzle
* [Pool de Conexões no MySQL](https://villagesql.com/docs/pt-BR/guides/connection-pooling.md) — como o pool de conexões que o `mysql2` cria se encaixa nos limites de conexão do MySQL


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.