# Bases de dados com Claude Code: esquema, queries e migrações

Conetores MCP, agentes e skills para esquema, queries SQL, migrações e desempenho.

Quase todos os projetos acabam com uma base de dados no centro. O problema raramente aparece no primeiro dia: aparece quando a tabela de encomendas chega aos milhões de linhas, quando uma query que corria em 20 ms passa a segurar a página inteira, ou quando é preciso alterar uma coluna numa base de dados que está em produção e não pode parar. Nessa altura o trabalho deixa de ser escrever SQL e passa a ser perceber o que a base de dados está mesmo a fazer.

Os componentes desta página tratam de três coisas distintas. Os conetores (MCP) dão ao Claude Code uma ligação real à sua base de dados, para que possa listar tabelas, ler o esquema e correr queries em vez de adivinhar a partir do código da aplicação. Os agentes e as skills trazem o método: como normalizar um modelo, que índice criar a partir de um plano de execução, como partir uma migração em passos reversíveis.

Comece pelo conetor do motor que utiliza, porque quase tudo o resto melhora quando o Claude Code consegue ver o esquema verdadeiro. Depois escolha por problema concreto: desenho de raiz, query lenta, ou alteração de esquema em produção. Evite instalar tudo. Dois ou três componentes bem escolhidos rendem mais do que uma lista longa que ninguém revê, e a maioria pede apenas uma variável de ambiente com a string de ligação.


## Conetores (MCP) para ligar à base de dados

Estes conetores dão ao Claude Code acesso direto ao motor, através de uma string de ligação guardada em variável de ambiente. Sem eles, o Claude Code só conhece o esquema que consegue inferir do código.

- **postgresql-integration** (Conetores): Assenta no servidor @modelcontextprotocol/server-postgres e liga-se por POSTGRES_CONNECTION_STRING, o caminho mais direto para explorar tabelas e correr queries num Postgres já existente. [ficha](https://doutorai.pt/componentes/mcps__postgresql-integration)
- **mysql-integration** (Conetores): Para quem tem o projeto assente em MySQL: arranca com uvx e pede apenas MYSQL_CONNECTION_STRING, dando acesso aos dados e à gestão da base de dados dentro da sessão de trabalho. [ficha](https://doutorai.pt/componentes/mcps__mysql-integration)
- **supabase** (Conetores): Liga ao seu projeto Supabase com os argumentos --read-only e --project-ref, o que mantém a sessão limitada à leitura. Autentica-se com um token de acesso pessoal. [ficha](https://doutorai.pt/componentes/mcps__supabase)
- **mongodb** (Conetores): Vem configurado com --readOnly, por isso serve bem para inspecionar coleções e documentos de um MongoDB local ou de um cluster Atlas sem risco de escrever por engano. [ficha](https://doutorai.pt/componentes/mcps__mongodb)
- **redis** (Conetores): Servidor oficial da Redis para consultar e gerir dados em linguagem natural, útil quando a dúvida é o que está realmente em cache e sob que chaves. [ficha](https://doutorai.pt/componentes/mcps__redis)
- **dbhub** (Conetores): Alternativa a considerar quando o projeto toca em vários motores: um único conetor cobre PostgreSQL, MySQL, MariaDB, SQL Server e SQLite a partir de um DSN. [ficha](https://doutorai.pt/componentes/mcps__dbhub)

## Desenho de esquema e modelação de dados

Para quando o modelo ainda está a ser decidido, ou quando o que existe já não aguenta os acessos que a aplicação faz.

- **database-architect** (Agentes): Ponto de partida para decisões de arquitetura: escolha de tecnologia, modelação e padrões de dados em microserviços. Planeia e desenha, passando a afinação fina do Postgres a agentes especializados. [ficha](https://doutorai.pt/componentes/agents__database-architect)
- **database-schema-designer** (Skills): Descreva o domínio e receba um esquema com normalização, restrições e índices já pensados, para SQL ou NoSQL. Boa escolha para sair da folha em branco sem perder integridade de dados. [ficha](https://doutorai.pt/componentes/skills__database-schema-designer)
- **postgresql** (Skills): Específica do Postgres: tipos de dados, índices, restrições e funcionalidades avançadas. Utilize depois de o motor estar decidido, para o esquema aproveitar o que o Postgres tem de próprio. [ficha](https://doutorai.pt/componentes/skills__postgresql)
- **supabase-schema-architect** (Agentes): Em projetos Supabase o esquema não se separa das políticas RLS. Este agente trata das duas coisas em conjunto, incluindo o planeamento das migrações que daí resultam. [ficha](https://doutorai.pt/componentes/agents__supabase-schema-architect)
- **nosql-specialist** (Agentes): Quando os dados não encaixam bem em tabelas: modelação e decisões de arquitetura para MongoDB, Redis, Cassandra e outros armazenamentos de documentos ou chave-valor. [ficha](https://doutorai.pt/componentes/agents__nosql-specialist)

## Queries lentas, índices e desempenho

O grupo a abrir quando a aplicação já funciona mas há páginas a demorar, ou a carga da base de dados a subir sem explicação clara.

- **sql-pro** (Agentes): Para SQL complexo que atravessa PostgreSQL, MySQL, SQL Server e Oracle. Trata da reescrita de queries pesadas e das estratégias de índices quando o desempenho já é o problema. [ficha](https://doutorai.pt/componentes/agents__sql-pro)
- **database-optimization** (Agentes): Trabalha a partir de medições em vez de palpites: perfila primeiro, usa EXPLAIN ANALYZE para ler o plano de execução e só depois desenha índices segundo os padrões de acesso reais. [ficha](https://doutorai.pt/componentes/agents__database-optimization)
- **supabase-postgres-best-practices** (Skills): Reúne práticas de desempenho para Postgres publicadas pela Supabase, aplicáveis ao escrever, rever ou afinar queries, desenhos de esquema e configurações da base de dados. [ficha](https://doutorai.pt/componentes/skills__supabase-postgres-best-practices)
- **postgresql-optimization** (Skills): Fluxo de trabalho fechado para afinação de queries em Postgres, com análise de desempenho, estratégias de indexação e gestão da base de dados em produção. [ficha](https://doutorai.pt/componentes/skills__postgresql-optimization)
- **mongodb-performance-advisor** (Agentes): Do lado do MongoDB, analisa o desempenho da base de dados e devolve recomendações concretas sobre queries e índices, em vez de conselhos genéricos de modelação. [ficha](https://doutorai.pt/componentes/agents__mongodb-performance-advisor)

## Migrações e alterações de esquema em produção

Mudar o esquema de uma base de dados viva é a parte com mais risco. Estes componentes tratam de versionamento, reversão e passos que não param o serviço.

- **database-migration** (Skills): Cobre migrações de esquema e de dados em Sequelize, TypeORM e Prisma, com estratégias de reversão e passos que evitam interrupção de serviço. Serve também para mudar de ORM. [ficha](https://doutorai.pt/componentes/skills__database-migration)
- **create-database-migrations** (Comandos): Deteta o ORM a partir do package.json ou do requirements.txt, procura as migrações que já existem no repositório e cria a nova com versionamento e reversão desde o início. [ficha](https://doutorai.pt/componentes/commands__create-database-migrations)
- **supabase-migration-assistant** (Comandos): Gera e gere migrações Supabase com testes e validação automáticos, indicado para quem já tem o projeto e o esquema assentes na Supabase. [ficha](https://doutorai.pt/componentes/commands__supabase-migration-assistant)
- **prisma-expert** (Skills): Em projetos com Prisma os problemas concentram-se em quatro sítios: schema, migrações que falham, relações mal modeladas e queries lentas. É exatamente esse o âmbito desta skill. [ficha](https://doutorai.pt/componentes/skills__prisma-expert)

## Como instalar cada tipo de componente

Os quatro tipos instalam-se de maneira diferente. Agentes ficam em .claude/agents/, skills em .claude/skills/ e comandos em .claude/commands/, dentro do projeto ou na pasta pessoal, e o Claude Code carrega-os na sessão seguinte. Os conetores (MCP) não são ficheiros markdown: são um bloco JSON com a chave mcpServers, que indica o comando a executar (npx ou uvx) e as variáveis de ambiente necessárias. A string de ligação não deve ficar escrita em texto simples num repositório partilhado. Guarde-a numa variável de ambiente do sistema ou num ficheiro .env fora do controlo de versões, e confirme a ligação com uma consulta de leitura antes de dar qualquer instrução de escrita.

## Comece sempre em modo de leitura

Os conetores desta página têm posturas diferentes quanto à escrita. O do MongoDB traz --readOnly e o da Supabase traz --read-only nos argumentos, o que limita a sessão a consultas. Já os de PostgreSQL, MySQL e dbhub dependem inteiramente das permissões do utilizador que colocar na string de ligação. A forma prudente de começar é criar na base de dados um utilizador só com SELECT e apontar o conetor para esse utilizador. Fica com a parte que interessa, que é o Claude Code ver o esquema verdadeiro e os dados verdadeiros, sem que um pedido mal interpretado se transforme num UPDATE sem cláusula WHERE.

## Como combinar estes componentes numa tarefa

Estes componentes rendem mais encadeados do que isolados. Um exemplo comum: o conetor de PostgreSQL dá acesso ao esquema e aos planos de execução, o agente de otimização lê esses planos e propõe um índice, e a skill de migrações transforma esse índice num ficheiro versionado com reversão, em vez de um comando escrito à mão na consola. O mesmo encadeamento funciona no desenho de raiz, com o agente de arquitetura a decidir motor e modelo e a skill específica do Postgres a afinar tipos e restrições. Evite carregar dois componentes que fazem o mesmo, porque o Claude Code passa a ter instruções concorrentes para a mesma decisão.

## Perguntas frequentes

### Preciso mesmo de um conetor MCP ou basta um agente?

São coisas diferentes. Um agente ou uma skill trazem método e conhecimento, mas trabalham apenas com o que conseguem ler no código do projeto. Um conetor (MCP) liga o Claude Code ao motor e permite listar tabelas, consultar o esquema e correr queries. Para desenhar de raiz, o agente chega. Para diagnosticar uma query lenta numa base de dados que já existe, o conetor faz a diferença.

### É seguro dar ao Claude Code acesso à base de dados de produção?

Não é o ponto de partida aconselhável. Utilize uma cópia ou um ambiente de testes sempre que for possível. Se tiver mesmo de ser produção, crie um utilizador dedicado apenas com permissões de leitura, ative as opções de leitura do conetor quando existirem, e reveja qualquer SQL de escrita antes de o executar.

### Qual escolher entre os vários agentes de otimização?

Depende do motor e da fase em que está. Para SQL complexo em vários motores, o sql-pro. Para partir de um plano de execução e chegar a índices, o database-optimization. Em Postgres, as skills específicas entram em detalhe que os agentes genéricos não cobrem. No MongoDB, o raciocínio sobre índices é outro e pede o agente próprio.

### Estes componentes servem para bases de dados NoSQL?

Servem, mas com menos escolha. Há um conetor para MongoDB, outro para Redis, um agente de modelação para armazenamentos de documentos e chave-valor, e um agente de desempenho para MongoDB. A maior parte do resto desta página assume SQL, sobretudo Postgres, que é onde a biblioteca técnica do Doutor AI tem mais material disponível.

### As migrações geradas podem ser aplicadas sem revisão?

Não. Uma migração é código que altera dados que já existem e nem sempre é reversível. Leia o ficheiro gerado, confirme que tem passo de reversão, e teste primeiro numa cópia do esquema com volume de dados parecido. Alterações a colunas com muitas linhas podem bloquear tabelas, e isso só se nota com dados reais.


Fonte: https://doutorai.pt/para/bases-de-dados - Doutor AI, selecao feita a mao da biblioteca tecnica.