Como instalar Prisma 7 com PostgreSQL

Para instalar Prisma 7 com PostgreSQL, configure o projeto como ESM, instale Prisma Client, CLI, pg e @prisma/adapter-pg, crie prisma.config.ts, defina um output no generator e entregue o adapter ao new PrismaClient. Ao final, uma consulta real mostrará a versão do banco e um registro criado.

Esta lição parte de Node e npm funcionando. Ela usa um PostgreSQL descartável em Docker para não tocar no banco de outro projeto. Se você ainda mistura banco, SQL e ORM, leia primeiro o guia de Prisma e o guia de PostgreSQL.

A tomada, o aparelho e o adaptador

Imagine um aparelho com um plugue e uma tomada de outro padrão. Saber que ambos trabalham com energia não faz o encaixe acontecer; você precisa de uma peça que traduza o formato de conexão. No Prisma 7, o Client é o aparelho, o driver pg é a conexão PostgreSQL e @prisma/adapter-pg é o adaptador entre eles.

O mapeamento técnico vai além do nome: Prisma Client produz operações, o adapter converte a chamada para a interface do driver e pg mantém conexões com o servidor. O limite da analogia é que o adapter também transporta erros e opções de pool; ele não é apenas um formato físico. Sem ele, o Client atual nem inicia a conexão.

Esse é o primeiro modelo mental para reconhecer tutorial desatualizado. Se o código chama new PrismaClient() sem opções e diz que está ensinando Prisma 7 com PostgreSQL, falta uma peça obrigatória.

Confirme as versões antes de criar arquivos

Os exemplos foram executados com Node 24.16.0 e Prisma 7.9.1. Confira Node e npm:

node --version
npm --version

Crie um diretório vazio e inicie o projeto. Depois marque o pacote como ESM:

npm init -y
npm pkg set type=module

No package.json, a decisão fica visível:

{
  "type": "module"
}

Esse trecho é apenas a parte relevante; mantenha nome, versão, scripts e dependências criados pelo npm. Para revisar a função do arquivo, veja npm e package.json.

Instale CLI, Client, driver e adapter separadamente

Prisma CLI participa do desenvolvimento, então fica em devDependencies. Client, adapter e driver são usados pela aplicação em runtime:

npm install @prisma/client@7.9.1 @prisma/adapter-pg@7.9.1 pg dotenv
npm install --save-dev prisma@7.9.1 typescript tsx @types/node @types/pg
npx prisma --version

Fixar os dois pacotes Prisma na mesma versão torna o ambiente reproduzível. Em 22 de agosto de 2026, 7.9.1 é GA e está no canal latest; Prisma 8 aparece no canal next como RC. Não troque o número deste tutorial por @next num projeto que precisa de estabilidade.

Deixe o init criar a estrutura da versão atual

Use o provider PostgreSQL, escolha o output e mantenha esta prática focada sem instalar arquivos de skills do CLI:

npx prisma init \
  --datasource-provider postgresql \
  --output ../src/generated/prisma \
  --no-skills

O comando cria duas fontes diferentes. schema.prisma descreve modelos e o provider. prisma.config.ts configura a CLI. Essa separação é parte do Prisma 7; uma URL copiada para datasource db vem de material antigo.

Configure generator e datasource

Abra prisma/schema.prisma e deixe a base assim:

generator client {
  provider     = "prisma-client"
  output       = "../src/generated/prisma"
  moduleFormat = "esm"
}

datasource db {
  provider = "postgresql"
}

O provider do generator é prisma-client, não prisma-client-js. O output é obrigatório no Prisma 7 e aponta para código gerado que sua aplicação importará. datasource db informa qual dialeto e conjunto de tipos o schema usa; a URL fica na configuração abaixo.

import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

O nome técnico é Prisma Config. Em palavras simples, ele diz à CLI onde estão schema, histórico de migration e conexão. env falha cedo quando a URL não existe, em vez de entregar undefined a um comando que mudará o banco.

Suba um PostgreSQL que possa ser descartado

O container abaixo usa nome específico, banco e senha apenas locais:

docker run -d --name prisma-postgres-local \
  -e POSTGRES_USER=devclub \
  -e POSTGRES_PASSWORD=devclub_test_only \
  -e POSTGRES_DB=livraria_prisma \
  -p 5432:5432 \
  postgres:18-alpine

Coloque a conexão no .env e não envie senhas reais ao Git:

DATABASE_URL="postgresql://devclub:devclub_test_only@localhost:5432/livraria_prisma?schema=public"

Confirme o servidor, não apenas a tag da imagem:

docker exec prisma-postgres-local \
  psql -U devclub -d livraria_prisma -Atc 'SHOW server_version;'

Se a porta 5432 estiver ocupada, publique outra porta do host e atualize a URL. Isso muda o endereço externo, não a porta 5432 dentro do container.

Crie um modelo pequeno e valide

Acrescente Livro ao schema:

model Livro {
  id      Int    @id @default(autoincrement())
  titulo  String
  slug    String @unique
  estoque Int    @default(0)

  @@map("livros")
}

Rode validação, migration e geração como etapas explícitas:

npx prisma validate
npx prisma migrate dev --name inicial
npx prisma generate

O timestamp da sua pasta será diferente. Abra o migration.sql e confirme que há CREATE TABLE "livros" e índice único para slug. generate vem depois porque o Prisma 7 não o dispara automaticamente em migrate dev.

Conecte o Client pelo adapter

Crie src/prisma.ts:

import "dotenv/config";
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "./generated/prisma/client.js";

const connectionString = process.env.DATABASE_URL;

if (!connectionString) {
  throw new Error("DATABASE_URL não foi definida");
}

const adapter = new PrismaPg({ connectionString });
export const prisma = new PrismaClient({ adapter });

Crie src/index.ts para gravar e ler:

import { prisma } from "./prisma.js";

const livro = await prisma.livro.create({
  data: { titulo: "Olhos d'água", slug: "olhos-dagua", estoque: 8 },
});

console.log({ titulo: livro.titulo, estoque: livro.estoque });
await prisma.$disconnect();

npx tsx src/index.ts

O registro veio do PostgreSQL. O tipo de livro foi gerado a partir do modelo e o adapter abriu a conversa pelo driver pg. Em servidor web, compartilhe uma instância adequada ao ciclo de vida do processo em vez de conectar e desconectar a cada requisição.

Reproduza o erro que denuncia tutorial antigo

Retire o adapter e tente construir apenas o Client:

import { PrismaClient } from "./generated/prisma/client.js";

new PrismaClient();

O TypeScript já mostra TS2554: Expected 1 arguments, but got 0. Executado sem checagem, o mesmo problema aparece no runtime:

Não resolva instalando aleatoriamente outra versão. Volte à arquitetura: importe PrismaPg, crie o adapter com connectionString e passe { adapter }. Esse padrão identifica a diferença entre Prisma 6 e 7.

Missão: reinstale sem consultar o bloco pronto

Num segundo diretório, crie o projeto a partir de quatro pistas: ESM no package.json, URL em prisma.config.ts, generator prisma-client com output e PrismaClient com adapter. Modele Categoria com id e nome @unique, migre, gere e crie uma categoria.

Seu critério de sucesso tem cinco provas: prisma --version mostra 7.9.1; prisma validate passa; a pasta gerada está em src; PostgreSQL responde 18.6; e retirar { adapter } reproduz o erro acima. Ao terminar, remova apenas o container desta prática:

docker rm -f prisma-postgres-local

Com a conexão compreendida, avance para schema e modelos no Prisma e transforme os campos em constraints e tipos de verdade.