Projetando esquemas e consultas de banco de dados com Claude Code: guia prático (2026)

O Claude Code consegue mesmo projetar um BD e escrever consultas?

Sim — e faz isso muito bem, porque projetar esquemas e escrever consultas são justamente o tipo de trabalho para o qual uma ferramenta agêntica como o Claude Code foi criada. O Claude Code não é só sugestão no estilo autocomplete: ele consegue ler seus arquivos e o repositório inteiro, rodar comandos no terminal (psql, mongosh, executar testes), ler a saída e iterar para se corrigir sozinho. Para bancos de dados, esse ciclo — "ler o contexto → gerar DDL/consulta → executar → ler o resultado → ajustar" — é onde ele fica mais forte.

Este guia foca nos dois sistemas mais comuns: PostgreSQL (relacional) e MongoDB (documento). A mesma abordagem funciona para os dois. Se você está começando agora e ainda não sabe bem o que é o Claude Code, leia primeiro o que é o Claude Code e para que você o usa e depois volte aqui.

Um alerta sincero logo de cara: a IA é rápida com bancos de dados, mas não é automaticamente segura. Ela pode inventar nomes de colunas, escolher o tipo de dado errado para dinheiro ou gerar uma migração sem forma de desfazer. É por isso que todo este guia se apoia em dois princípios: conceder apenas acesso somente leitura à produção e sempre dar ao Claude uma forma de conferir o próprio trabalho. Vamos percorrer o ciclo completo: conectar → projetar o esquema → escrever consultas → índices e desempenho → migrações.

Configuração: conectando o Claude Code ao seu banco de dados

Antes de pedir qualquer coisa ao Claude, ele precisa de fato "enxergar" seus dados. Há três formas, da mais segura à mais flexível:

Opção 1 - servidor MCP (recomendada, somente leitura)

O MCP (Model Context Protocol) é a forma padrão de o Claude Code se conectar a ferramentas externas, incluindo bancos de dados. A documentação de MCP do Claude Code dá um exemplo direto de consulta a dados "com base no nosso banco PostgreSQL" (documentação de MCP do Claude Code, Anthropic, 2026). O comando para adicionar um servidor MCP por HTTP:

claude mcp add --transport http postgres-db https://your-mcp-endpoint

O detalhe de segurança decisivo: o servidor MCP de referência para Postgres é descrito como "acesso somente leitura ao banco com inspeção de esquema" — ou seja, ele apenas lê e inspeciona a estrutura, não escreve (modelcontextprotocol/servers, 2026; esse servidor foi movido desde então para o repositório servers-archived). É exatamente isso que você quer ao deixar a IA perto do seu BD: ela pode ler o esquema para entender o contexto, mas não pode apagar suas tabelas por conta própria. Se o MCP é novidade para você, veja o que é o MCP e como conectar ferramentas externas ao Claude Code.

Opção 2 - CLI psql / mongosh

Mais simples ainda: é só deixar o Claude rodar comandos pelo terminal. Se você já tem o psql ou o mongosh configurado, o Claude pode chamá-los diretamente. Isso é flexível (ele também pode rodar comandos de escrita), mas é justamente por isso que é mais arriscado — aponte-o só para um BD de dev/local, nunca para uma string de conexão de produção com permissão de escrita.

Opção 3 - colar um arquivo de esquema com @

Quando você ainda não está pronta para conectar um BD de verdade, é só entregar ao Claude o seu arquivo schema.sql ou uma descrição das suas tabelas usando a sintaxe @:

Read @db/schema.sql and summarize the tables, primary keys, and relationships.
Then list 3 design risks you see.

Passo 1 - Projete o esquema com o Claude Code

O erro mais comum é abrir o Claude e digitar de imediato "crie uma tabela de usuários para mim". Faça isso e você recebe de volta um esquema genérico que a IA chutou. O jeito certo é carga de trabalho primeiro: decida o tipo de carga antes e só então deixe a IA montar as tabelas.

Classifique a carga de trabalho primeiro

Pergunte a si mesma (e conte ao Claude) que tipo de aplicação é essa, porque cada tipo otimiza para um formato de dados diferente:

Use o modo de plano para o Claude ler antes de escrever

Ative o modo de plano (pressione Shift+Tab para alternar entre os modos) e peça ao Claude para ler os requisitos, perguntar sobre qualquer coisa que esteja pouco clara e só então gerar o DDL. Isso o impede de sair criando tabelas às pressas em cima de uma suposição errada.

Padrão de prompt: declare invariantes, não colunas

Em vez de listar colunas, descreva as regras de negócio invariantes para que a própria IA defina a chave primária, as restrições únicas e as chaves estrangeiras corretas:

Design a PostgreSQL schema for a small shop. Workload: OLTP.
Invariants:
- One email belongs to exactly one account (unique).
- An order must belong to an existing user (an orphan = a bug).
- Each order_items row records the price AT PURCHASE TIME, not the current price.
- Money must be exact, with no rounding error.
Ask me questions if anything is missing before writing the DDL.

Checklist relacional (para revisar o DDL que o Claude gera)

• Dê nomes de substantivos às entidades; nomeie uma tabela de junção conforme a relação que ela representa.
• A identidade estável vai na chave primária; uma regra de negócio única vai numa restrição de unicidade.
• Use uma chave estrangeira sempre que um dado órfão seria um bug.
• Dinheiro, quantidades e tempo usam tipos exatos — nunca float para dinheiro (use numeric/decimal).
• Muitos-para-muitos: crie uma tabela de junção dedicada e adicione as colunas de metadados úteis.
• Só adicione um índice para um predicado que você provou precisar (não indexe tudo).

Um exemplo real — um esquema mínimo de e-commerce que o Claude produziu (com uma linha que eu corrigi, veja a nota):

CREATE TABLE users (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 email text NOT NULL UNIQUE,
 created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE orders (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 user_id bigint NOT NULL REFERENCES users(id),
 status text NOT NULL DEFAULT 'pending',
 created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE order_items (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 order_id bigint NOT NULL REFERENCES orders(id),
 product_id bigint NOT NULL,
 quantity int NOT NULL CHECK (quantity > 0),
 unit_price numeric(12,2) NOT NULL -- NOT float: money must be exact
);

Na primeira vez, o Claude deixou unit_price como real (um float). Fiz com que ele mudasse para numeric(12,2) — essa é exatamente a classe de bug que você precisa vigiar por conta própria, porque a IA nem sempre se lembra dela.

PostgreSQL ou MongoDB? Escolha pelo padrão de acesso

Não escolha por preferência, escolha por como os dados são lidos e escritos. Uma tabela rápida:

A regra de ouro do MongoDB quando você está dividida entre embutir e referenciar:

• Embutir (Embed) quando o dado filho é lido/escrito junto com o pai e tem tamanho limitado (por exemplo, um endereço de entrega dentro de um pedido).
• Referenciar (Reference) quando o dado cresce sem limite, é compartilhado por muitos pais ou precisa do próprio ciclo de vida (por exemplo, os comentários de um post viral).

Passo 2 - Escreva e otimize consultas com o Claude Code

É aqui que o Claude Code brilha: você descreve o resultado que quer em português simples, ele escreve a consulta, explica e então otimiza. Em SQL, ele é fluente em JOINs, subconsultas, CTEs e funções de janela. Para MongoDB, ele monta pipelines de agregação ($match → $group → $lookup).

Um exemplo real — relatório de receita mensal. O prompt:

Write a Postgres query for total revenue per month in 2026,
counting only orders with status = 'paid'. Use a CTE for readability,
with a short explanation.

O Claude retorna:

WITH paid_items AS (
 SELECT o.created_at, oi.quantity * oi.unit_price AS line_total
 FROM orders o
 JOIN order_items oi ON oi.order_id = o.id
 WHERE o.status = 'paid'
 AND o.created_at >= '2026-01-01'
 AND o.created_at < '2027-01-01'
)
SELECT date_trunc('month', created_at) AS month,
 SUM(line_total) AS revenue
FROM paid_items
GROUP BY 1
ORDER BY 1;

Saída ao executar (dados de exemplo):

 month | revenue
--------------------+-----------
 2026-01-01 00:00:00 | 154200.00
 2026-02-01 00:00:00 | 187650.50
 2026-03-01 00:00:00 | 203110.00

No MongoDB, a mesma ideia é um pipeline: $match filtra os pedidos paid, $unwind abre o array de itens, $group agrupa por mês. Peça ao Claude para escrevê-lo e depois explicar cada estágio — o jeito mais rápido de obter ao mesmo tempo uma consulta e o entendimento dela.

Aviso importante: sempre releia a consulta que o Claude escreveu antes de rodá-la contra dados reais. Um UPDATE/DELETE sem o WHERE — que a IA pode produzir por engano — pode apagar uma tabela inteira. Leia, entenda e só então aperte Enter.

Passo 3 - Índices e desempenho com EXPLAIN ANALYZE

Uma consulta que roda corretamente não basta, ela tem que rodar rápido. Faça o Claude executar EXPLAIN ANALYZE (Postgres) ou .explain() (Mongo), ler o plano e então sugerir um índice — no lugar certo, não às cegas.

Run EXPLAIN ANALYZE for the revenue query above.
If you see a Seq Scan on orders, suggest a suitable index and explain why.

Numa tabela orders grande, o plano inicial costuma mostrar um Seq Scan porque filtra por status e created_at. Adicione o índice certo:

CREATE INDEX idx_orders_status_created
 ON orders (status, created_at);

Rode de novo e o plano muda para um Index Scan, e o tempo da consulta cai visivelmente. O ponto em que você quer a ajuda do Claude é escolher a ordem das colunas em um índice composto para que ele combine com o predicado — é aqui que os devs mais novos costumam errar.

O princípio de indexação que evita o excesso de índices (algo que o próprio Claude tende a exagerar): indexe apenas chaves estrangeiras, colunas em que você filtra/ordena com frequência e restrições de unicidade. Cada índice que você adiciona deixa as escritas mais lentas e custa armazenamento, então não indexe "por via das dúvidas". Se você disser ao Claude "adicione índices para deixar mais rápido", ele tende a exagerar — peça que proponha apenas índices com um predicado comprovável.

Passo 4 - Migrações seguras com o Claude Code

Mudar o esquema em um sistema em produção é a tarefa mais propensa a incidentes que existe. Um processo seguro para quando você deixa o Claude gerar uma migração:

1. Sempre inclua um rollback. Toda migração "up" precisa ter uma "down" correspondente. Peça ao Claude para escrever as duas e explicar como desfazer a mudança.
2. Teste primeiro numa cópia. Rode a migração em um BD de dev ou num snapshot da produção, nunca direto na produção.
3. Compare antes/depois. Conte as linhas e confira alguns registros de amostra antes e depois para garantir que nenhum dado foi perdido.
4. Revise o diff com um subagente. Faça um subagente revisar a migração como um PR independente, procurando operações destrutivas (DROP, alterar um tipo de dado) que não tenham uma etapa de segurança.

As boas práticas da Anthropic resumem esse princípio em uma frase: "dê ao Claude uma forma de verificar o trabalho dele" (boas práticas do Claude Code, Anthropic, 2026). Para bancos de dados, "verificar" significa algo concreto: rodar testes, rodar EXPLAIN e comparar a contagem de linhas antes e depois — e não acreditar na palavra da IA de que está "pronto".

Uma proteção que vale configurar: use um hook de permissão para impedir que o Claude escreva sozinho no diretório migrations/, ou para bloquear comandos DDL destrutivos, forçando toda mudança a passar pela sua revisão. Para mais sobre apertar as permissões com segurança, veja como fazer uma auditoria de segurança com o Claude Code.

Armadilhas reais quando você deixa a IA cuidar de bancos de dados (leia antes da produção)

Esta seção é a que mais importa, e quase nenhuma documentação diz isso em voz alta. A IA é rápida com BDs, mas é aqui que ela realmente erra — eu bati em todas essas:

• Inventar nomes de colunas/tabelas. Às vezes o Claude referencia uma coluna que não existe porque chutou o esquema. Sempre deixe-o ler o esquema real (via MCP ou @schema.sql) antes de escrever uma consulta.
• Tipo errado para dinheiro. Ele recorre com muita frequência a float/real para preços, causando erros de arredondamento que se acumulam. Exija numeric/decimal.
• Excesso de índices. Espalhar índices por todo lado deixa as escritas mais lentas sem acelerar as leituras de forma significativa.
• Migrações sem rollback. Gerar o up mas esquecer o down, deixando você presa quando precisar desfazer.
• Consultas N+1 ou de varredura completa. Escrever um laço que consulta registro por registro em vez de um único JOIN, ou deixar cair uma condição de filtro.

Três regras inegociáveis: (1) conceda acesso somente leitura à produção apenas — deixe a IA ler, nunca escrever; (2) toda mudança de esquema passa por um PR + testes, nunca aplicada diretamente; (3) verifique com EXPLAIN + comparação de contagem de linhas, não confie no "pronto". Faça essas três coisas e usar IA no seu BD é perfeitamente seguro.

Vá mais rápido com a skill ak-databases (AgentKit)

Se você se pega reescrevendo o prompt de "carga primeiro, declare os invariantes, inclua o checklist" toda santa vez, existe um atalho honesto: o AgentKit Engineer Kit (que contém a skill ak-databases) empacota exatamente a espinha dorsal deste artigo. A skill ak-databases cobre design de esquema OLTP/OLAP, escrita de consultas Postgres/Mongo, agregação, indexação e migrações, junto com scripts como db_migrate.py, db_backup.py e db_performance_check.py. Você só digita naturalmente — "projete um esquema para..." — e a skill se ativa sozinha, então você não precisa decorar o padrão do prompt.

Perguntas frequentes (FAQ)

O Claude Code consegue se conectar diretamente a um banco de dados?

Sim, de duas formas: um servidor MCP (recomendado, geralmente somente leitura) ou deixar o Claude rodar comandos psql/mongosh pelo terminal. Quando você ainda não quer conectar um BD de verdade, pode colar o arquivo de esquema usando a sintaxe @.

O Claude Code vai rodar consultas em produção por conta própria?

Você não deveria dar essa capacidade a ele. Conceda apenas uma conexão somente leitura à produção e mantenha todas as operações de escrita/DDL em um BD de dev ou por trás de um PR revisado. Use um hook de permissão para bloquear comandos destrutivos.

Devo escolher PostgreSQL ou MongoDB?

Escolha pelo padrão de acesso, não pela preferência. PostgreSQL para transações que precisam de restrições rígidas e para relatórios agregados; MongoDB para dados aninhados lidos/escritos como uma unidade. Transações de dinheiro deveriam quase sempre ser PostgreSQL.

O Claude Code consegue escrever migrações?

Sim, mas você precisa pedir que ele escreva também a etapa de rollback (down), testar primeiro numa cópia e comparar a contagem de linhas antes e depois de rodar. Não aplique uma migração gerada por IA direto na produção.

É seguro deixar a IA cuidar de bancos de dados?

É seguro se você seguir três regras: somente leitura na produção, toda mudança por um PR + testes e verificação com EXPLAIN ANALYZE + comparação de contagem de linhas. O risco de verdade vem de conceder acesso de escrita e confiar na IA sem conferir.

Preciso comprar o Engineer Kit?

Não. Todo o fluxo deste artigo funciona com o Claude Code puro. A skill ak-databases só o torna mais rápido e mais consistente quando você faz trabalho de BD com regularidade ou em equipe.

Conclusão e próximos passos

Recapitulando os quatro passos: conecte o BD (prefira MCP somente leitura) → projete o esquema pela carga de trabalho → escreva e otimize consultas com verificação → migre com um rollback. A chave não é deixar a IA fazer tudo por você, mas dar a ela contexto suficiente e sempre uma forma de conferir o próprio trabalho. Uma vez pronto o esquema, o próximo passo lógico é ligar o BD à sua camada de API — veja como construir um backend e uma API com o Claude Code. E se você quer acelerar a parte de design do BD, pode experimentar a skill ak-databases no Engineer Kit.