Next.js + Prisma + PostgreSQL

Q: Qual a diferença entre prisma migrate dev e prisma db push?

migrate dev gera arquivos de migração SQL em prisma/migrations/ que você commita no controle de versão - é o fluxo de trabalho seguro para produção. db push sincroniza o schema diretamente sem criar arquivos de migração - use-o apenas para prototipagem rápida.

Q: Como executo migrações em produção?

Execute npx prisma migrate deploy como parte da sua etapa de build ou release. Isso aplica quaisquer migrações pendentes de prisma/migrations/ sem solicitar e sem gerar novas.

Q: Como faço o seeding do banco de dados?

Crie prisma/seed.ts, adicione "prisma": \{ "seed": "tsx prisma/seed.ts" \} ao package.json, depois execute npx prisma db seed. Ele também é executado automaticamente após prisma migrate reset.

Q: Armadilha: minha implantação no Vercel falha com "Query engine binary not found"

Adicione os binaryTargets corretos em schema.prisma: Em seguida, commite, redeploy e certifique-se de que prisma generate seja executado no seu build ("postinstall": "prisma generate" em package.json é a correção padrão).

Q: Armadilha: meus tipos não estão atualizando depois que mudei o schema

Execute npx prisma generate manualmente. O servidor TS do seu editor também pode precisar ser reiniciado. prisma migrate dev normalmente executa generate para você, mas db push e edições diretas do schema sem migração não o fazem.

Q: TypeScript: como tipar um resultado de consulta que inclui relações?

Use Prisma.GetPayload: Isso lhe dá um tipo preciso que corresponde à forma exata que findMany(\{ include: \{ author: true \} \}) retorna.

Q: TypeScript: como tipar uma Server Action que recebe um formulário?

Uma ação simples recebe FormData e retorna Promise: Para useActionState você adiciona um parâmetro prevState:

Uma configuração full-stack Next.js 15 com Prisma ORM, banco de dados PostgreSQL e Server Actions para mutações.

Receita

Crie um aplicativo Next.js 15 com Tailwind e TypeScript:

npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app

Instale o Prisma e o cliente:

npm install prisma @prisma/client
npm install -D prisma

Inicialize o Prisma com PostgreSQL:

npx prisma init --datasource-provider postgresql

Defina seu schema em prisma/schema.prisma.
Defina DATABASE_URL em .env.
Execute sua primeira migração:
```
npx prisma migrate dev --name init
```
Crie um singleton do Prisma client em lib/prisma.ts para evitar esgotar conexões durante o hot-reload.

Exemplo de Trabalho

Um aplicativo Todo completo com Prisma + PostgreSQL + Server Actions.

`prisma/schema.prisma`

generator client \{
  provider = "prisma-client-js"
\}
 
datasource db \{
  provider = "postgresql"
  url      = env("DATABASE_URL")
\}
 
model Todo \{
  id        String   @id @default(cuid())
  title     String
  completed Boolean  @default(false)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
\}

`lib/prisma.ts` (singleton)

import \{ PrismaClient \} from "@prisma/client";
 
const globalForPrisma = globalThis as unknown as \{
  prisma: PrismaClient | undefined;
\};
 
export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient(\{
    log: process.env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
  \});
 
if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

`app/page.tsx` (Server Component)

import \{ prisma \} from "@/lib/prisma";
import \{ addTodo \} from "./actions";
 
export default async function Home() \{
  const todos = await prisma.todo.findMany(\{
    orderBy: \{ createdAt: "desc" \},
  \});
 
  return (
    <main className="mx-auto max-w-xl p-8">
      <h1 className="text-2xl font-bold">Todos</h1>
 
      <form action=\{addTodo\} className="mt-4 flex gap-2">
        <input
          name="title"
          required
          className="flex-1 rounded border px-3 py-2"
          placeholder="New todo..."
        />
        <button type="submit" className="rounded bg-black px-4 py-2 text-white">
          Add
        </button>
      </form>
 
      <ul className="mt-6 space-y-2">
        \{todos.map((todo) => (
          <li key=\{todo.id\} className="rounded border p-3">
            \{todo.title\}
          </li>
        ))\}
      </ul>
    </main>
  );
\}

`app/actions.ts` (Server Action)

"use server";
 
import \{ prisma \} from "@/lib/prisma";
import \{ revalidatePath \} from "next/cache";
 
export async function addTodo(formData: FormData) \{
  const title = formData.get("title");
  if (typeof title !== "string" || title.trim() === "") return;
 
  await prisma.todo.create(\{
    data: \{ title: title.trim() \},
  \});
 
  revalidatePath("/");
\}

Aprofundamento

Como Funciona

O Prisma gera um cliente totalmente tipado com base no seu schema. O Server Component do Next.js é executado no servidor e consulta o Postgres diretamente através do cliente Prisma. Server Actions são endpoints POST criados automaticamente pelo Next.js - envios de formulário invocam a ação, que modifica o banco de dados e chama revalidatePath para limpar o render em cache, de modo que os novos dados apareçam na próxima solicitação.

O padrão singleton é crítico em desenvolvimento. O hot-reload do Next.js reavalia os módulos a cada alteração e, sem um singleton, você criaria um PrismaClient novo a cada recarregamento, esgotando rapidamente o pool de conexões do banco de dados.

Variações

PostgreSQL Hospedado: Supabase, Neon, Railway ou Vercel Postgres funcionam - basta colar a string de conexão deles em DATABASE_URL.
Desenvolvimento local com SQLite: altere provider = "sqlite" e use url = "file:./dev.db" para um banco de dados local sem configuração.
Seeding: adicione um script prisma/seed.ts e registre-o em "prisma": \{ "seed": "tsx prisma/seed.ts" \} no package.json, depois execute npx prisma db seed.
Prisma Studio: execute npx prisma studio para um navegador de dados e editor baseado em navegador.
Prisma Accelerate: pooling de conexões + cache global através de uma única URL prisma://, ideal para implantações serverless.
ORM Alternativo: Drizzle ORM oferece SQL tipado e um runtime mais leve.

Notas de TypeScript

O Prisma gera automaticamente tipos para cada modelo. Importe com import \{ Todo \} from "@prisma/client".
Para resultados de consulta com relações, use Prisma.TodoGetPayload<\{ include: \{ author: true \} \}> para derivar um tipo exato da forma retornada.
Server Actions podem ser tipados como (formData: FormData) => Promise<void> ou usar o padrão mais novo useActionState com um argumento prevState.
Habilite o modo estrito em tsconfig.json para capturar campos anuláveis - o Prisma respeita ? no schema como T | null em TS.

Armadilhas

Singleton ou morra. Sem o singleton globalThis em lib/prisma.ts, o modo de desenvolvimento do Next.js vazará conexões até que o Postgres recuse novas.
DATABASE_URL ausente. O Prisma nem sequer gerará sem ele. Coloque-o em .env (não apenas .env.local) porque a CLI do Prisma lê .env.
Esquecer prisma generate. Após alterar schema.prisma, regenere o cliente ou seus tipos ficarão desatualizados. prisma migrate dev faz isso automaticamente, mas prisma db push e edições manuais do schema podem não fazer.
Migrações de produção. Use prisma migrate deploy em CI/CD, nunca prisma migrate dev - este último pode solicitar interativamente e descartar dados.
Alvos binários para implantação. Em plataformas como Vercel ou AWS Lambda, você pode precisar adicionar binaryTargets = ["native", "rhel-openssl-3.0.x"] ao bloco do gerador, ou sua implantação falhará com "Query engine binary not found."
Limites de conexão em serverless. Cada invocação Lambda/Edge pode abrir uma nova conexão. Use PgBouncer, Prisma Accelerate ou uma string de conexão com pooling.
Incompatibilidade com runtime Edge. O cliente Prisma padrão não roda no Edge. Use Prisma Accelerate ou os Driver Adapters (atualmente em preview) para suporte ao edge.

Alternativas

Ferramenta	Estilo	Ideal para
Prisma	ORM com DSL de schema	ORM tipado completo, migrações, Studio
Drizzle ORM	Construtor de SQL tipado	Leve, amigável ao edge, mais próximo do SQL
Kysely	Construtor de consulta tipado	Equipes que querem SQL-first com inferência TS
postgres.js	Driver SQL bruto	Controle máximo, sem sobrecarga de abstração
Supabase client	SDK REST/Realtime	Auth + DB + realtime em um pacote

FAQs

Por que preciso de um singleton Prisma no Next.js?

O modo de desenvolvimento do Next.js recarrega módulos em alterações de arquivo. Cada recarregamento cria uma nova instância PrismaClient se você simplesmente new PrismaClient() no escopo do módulo, e cada instância abre seu próprio pool de conexões. Em poucos minutos, você atinge o limite de conexões do seu banco de dados. O singleton globalThis sobrevive ao hot-reload porque vive no objeto global, não no módulo.

Qual a diferença entre `prisma migrate dev` e `prisma db push`?

migrate dev gera arquivos de migração SQL em prisma/migrations/ que você commita no controle de versão - é o fluxo de trabalho seguro para produção. db push sincroniza o schema diretamente sem criar arquivos de migração - use-o apenas para prototipagem rápida.

Posso usar Prisma com runtime Edge?

Não com o cliente padrão. Você precisa do Prisma Accelerate (@prisma/extension-accelerate) ou dos Driver Adapters (atualmente em preview) que roteiam consultas através de um proxy baseado em fetch em vez de TCP do Node.

Como executo migrações em produção?

Execute npx prisma migrate deploy como parte da sua etapa de build ou release. Isso aplica quaisquer migrações pendentes de prisma/migrations/ sem solicitar e sem gerar novas.

Como faço o seeding do banco de dados?

Crie prisma/seed.ts, adicione "prisma": \{ "seed": "tsx prisma/seed.ts" \} ao package.json, depois execute npx prisma db seed. Ele também é executado automaticamente após prisma migrate reset.

Armadilha: minha implantação no Vercel falha com "Query engine binary not found"

Adicione os binaryTargets corretos em schema.prisma:

generator client \{
  provider      = "prisma-client-js"
  binaryTargets = ["native", "rhel-openssl-3.0.x"]
\}

Em seguida, commite, redeploy e certifique-se de que prisma generate seja executado no seu build ("postinstall": "prisma generate" em package.json é a correção padrão).

Armadilha: meus tipos não estão atualizando depois que mudei o schema

Execute npx prisma generate manualmente. O servidor TS do seu editor também pode precisar ser reiniciado. prisma migrate dev normalmente executa generate para você, mas db push e edições diretas do schema sem migração não o fazem.

TypeScript: como tipar um resultado de consulta que inclui relações?

Use Prisma.<Model>GetPayload:

import \{ Prisma \} from "@prisma/client";
 
type TodoWithAuthor = Prisma.TodoGetPayload<\{
  include: \{ author: true \};
\}>;

Isso lhe dá um tipo preciso que corresponde à forma exata que findMany(\{ include: \{ author: true \} \}) retorna.

TypeScript: como tipar uma Server Action que recebe um formulário?

Uma ação simples recebe FormData e retorna Promise<void>:

export async function addTodo(formData: FormData): Promise<void> \{ /* ... */ \}

Para useActionState você adiciona um parâmetro prevState:

export async function addTodo(prevState: State, formData: FormData): Promise<State> \{ /* ... */ \}

Devo chamar o Prisma de Client Components?

Não. O Prisma só roda no lado do servidor. Chame-o de Server Components, Server Actions, Route Handlers ou generateStaticParams. Se um Client Component precisar de dados, passe-os como props ou busque através de uma Server Action/Route Handler.

Como `revalidatePath` interage com mutações do Prisma?

revalidatePath("/") diz ao Next.js para descartar o render em cache para esse caminho. Na próxima solicitação, o Server Component é reexecutado, consulta o Prisma novamente e obtém os dados atualizados. Sem isso, os usuários veem dados desatualizados até que o cache expire.

Devo usar Prisma ou Drizzle?

Prisma tem melhor DX, Studio e migrações. Drizzle é mais leve, nativo para edge e oferece sintaxe semelhante a SQL com tipos fortes. Escolha Prisma para a maioria dos aplicativos full-stack; escolha Drizzle se você se preocupa com o tamanho do bundle, compatibilidade com edge ou deseja permanecer próximo ao SQL.

Relacionados

Receita

Crie um aplicativo Next.js 15 com Tailwind e TypeScript:

npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app

Instale o Prisma e o cliente:

npm install prisma @prisma/client
npm install -D prisma

Inicialize o Prisma com PostgreSQL:

npx prisma init --datasource-provider postgresql

Defina seu schema em prisma/schema.prisma.
Defina DATABASE_URL em .env.
Execute sua primeira migração:
```
npx prisma migrate dev --name init
```
Crie um singleton do Prisma client em lib/prisma.ts para evitar esgotar conexões durante o hot-reload.

Exemplo de Trabalho

Um aplicativo Todo completo com Prisma + PostgreSQL + Server Actions.

`prisma/schema.prisma`

generator client \{
  provider = "prisma-client-js"
\}
 
datasource db \{
  provider = "postgresql"
  url      = env("DATABASE_URL")
\}
 
model Todo \{
  id        String   @id @default(cuid())
  title     String
  completed Boolean  @default(false)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
\}

`lib/prisma.ts` (singleton)

import \{ PrismaClient \} from "@prisma/client";
 
const globalForPrisma = globalThis as unknown as \{
  prisma: PrismaClient | undefined;
\};
 
export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient(\{
    log: process.env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
  \});
 
if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

`app/page.tsx` (Server Component)

import \{ prisma \} from "@/lib/prisma";
import \{ addTodo \} from "./actions";
 
export default async function Home() \{
  const todos = await prisma.todo.findMany(\{
    orderBy: \{ createdAt: "desc" \},
  \});
 
  return (
    <main className="mx-auto max-w-xl p-8">
      <h1 className="text-2xl font-bold">Todos</h1>
 
      <form action=\{addTodo\} className="mt-4 flex gap-2">
        <input
          name="title"
          required
          className="flex-1 rounded border px-3 py-2"
          placeholder="New todo..."
        />
        <button type="submit" className="rounded bg-black px-4 py-2 text-white">
          Add
        </button>
      </form>
 
      <ul className="mt-6 space-y-2">
        \{todos.map((todo) => (
          <li key=\{todo.id\} className="rounded border p-3">
            \{todo.title\}
          </li>
        ))\}
      </ul>
    </main>
  );
\}

`app/actions.ts` (Server Action)

"use server";
 
import \{ prisma \} from "@/lib/prisma";
import \{ revalidatePath \} from "next/cache";
 
export async function addTodo(formData: FormData) \{
  const title = formData.get("title");
  if (typeof title !== "string" || title.trim() === "") return;
 
  await prisma.todo.create(\{
    data: \{ title: title.trim() \},
  \});
 
  revalidatePath("/");
\}

Aprofundamento

Como Funciona

Variações

PostgreSQL Hospedado: Supabase, Neon, Railway ou Vercel Postgres funcionam - basta colar a string de conexão deles em DATABASE_URL.
Desenvolvimento local com SQLite: altere provider = "sqlite" e use url = "file:./dev.db" para um banco de dados local sem configuração.
Seeding: adicione um script prisma/seed.ts e registre-o em "prisma": \{ "seed": "tsx prisma/seed.ts" \} no package.json, depois execute npx prisma db seed.
Prisma Studio: execute npx prisma studio para um navegador de dados e editor baseado em navegador.
Prisma Accelerate: pooling de conexões + cache global através de uma única URL prisma://, ideal para implantações serverless.
ORM Alternativo: Drizzle ORM oferece SQL tipado e um runtime mais leve.

Notas de TypeScript

O Prisma gera automaticamente tipos para cada modelo. Importe com import \{ Todo \} from "@prisma/client".
Para resultados de consulta com relações, use Prisma.TodoGetPayload<\{ include: \{ author: true \} \}> para derivar um tipo exato da forma retornada.
Server Actions podem ser tipados como (formData: FormData) => Promise<void> ou usar o padrão mais novo useActionState com um argumento prevState.
Habilite o modo estrito em tsconfig.json para capturar campos anuláveis - o Prisma respeita ? no schema como T | null em TS.

Armadilhas

Singleton ou morra. Sem o singleton globalThis em lib/prisma.ts, o modo de desenvolvimento do Next.js vazará conexões até que o Postgres recuse novas.
DATABASE_URL ausente. O Prisma nem sequer gerará sem ele. Coloque-o em .env (não apenas .env.local) porque a CLI do Prisma lê .env.
Esquecer prisma generate. Após alterar schema.prisma, regenere o cliente ou seus tipos ficarão desatualizados. prisma migrate dev faz isso automaticamente, mas prisma db push e edições manuais do schema podem não fazer.
Migrações de produção. Use prisma migrate deploy em CI/CD, nunca prisma migrate dev - este último pode solicitar interativamente e descartar dados.
Alvos binários para implantação. Em plataformas como Vercel ou AWS Lambda, você pode precisar adicionar binaryTargets = ["native", "rhel-openssl-3.0.x"] ao bloco do gerador, ou sua implantação falhará com "Query engine binary not found."
Limites de conexão em serverless. Cada invocação Lambda/Edge pode abrir uma nova conexão. Use PgBouncer, Prisma Accelerate ou uma string de conexão com pooling.
Incompatibilidade com runtime Edge. O cliente Prisma padrão não roda no Edge. Use Prisma Accelerate ou os Driver Adapters (atualmente em preview) para suporte ao edge.

Alternativas

Ferramenta	Estilo	Ideal para
Prisma	ORM com DSL de schema	ORM tipado completo, migrações, Studio
Drizzle ORM	Construtor de SQL tipado	Leve, amigável ao edge, mais próximo do SQL
Kysely	Construtor de consulta tipado	Equipes que querem SQL-first com inferência TS
postgres.js	Driver SQL bruto	Controle máximo, sem sobrecarga de abstração
Supabase client	SDK REST/Realtime	Auth + DB + realtime em um pacote

FAQs

Por que preciso de um singleton Prisma no Next.js?

Qual a diferença entre `prisma migrate dev` e `prisma db push`?

Posso usar Prisma com runtime Edge?

Como executo migrações em produção?

Execute npx prisma migrate deploy como parte da sua etapa de build ou release. Isso aplica quaisquer migrações pendentes de prisma/migrations/ sem solicitar e sem gerar novas.

Como faço o seeding do banco de dados?

Armadilha: minha implantação no Vercel falha com "Query engine binary not found"

Adicione os binaryTargets corretos em schema.prisma:

generator client \{
  provider      = "prisma-client-js"
  binaryTargets = ["native", "rhel-openssl-3.0.x"]
\}

Em seguida, commite, redeploy e certifique-se de que prisma generate seja executado no seu build ("postinstall": "prisma generate" em package.json é a correção padrão).

Armadilha: meus tipos não estão atualizando depois que mudei o schema

TypeScript: como tipar um resultado de consulta que inclui relações?

Use Prisma.<Model>GetPayload:

import \{ Prisma \} from "@prisma/client";
 
type TodoWithAuthor = Prisma.TodoGetPayload<\{
  include: \{ author: true \};
\}>;

Isso lhe dá um tipo preciso que corresponde à forma exata que findMany(\{ include: \{ author: true \} \}) retorna.

TypeScript: como tipar uma Server Action que recebe um formulário?

Uma ação simples recebe FormData e retorna Promise<void>:

export async function addTodo(formData: FormData): Promise<void> \{ /* ... */ \}

Para useActionState você adiciona um parâmetro prevState:

export async function addTodo(prevState: State, formData: FormData): Promise<State> \{ /* ... */ \}

Devo chamar o Prisma de Client Components?

Como `revalidatePath` interage com mutações do Prisma?

Devo usar Prisma ou Drizzle?

Next.js + Prisma + PostgreSQL

Buscar na documentação

Next.js + Prisma + PostgreSQL