Catálogos de esquema para assistentes de IA: a camada que ninguém quer manter

O catálogo de esquema para um assistente de IA é o artefato que responde à pergunta "como é que este banco de dados se parece agora". Seja o banco de dados Postgres, MySQL, SQL Server ou Redshift, a forma do problema é a mesma: o catálogo carrega nomes de tabelas, nomes de colunas, tipos, chaves e relacionamentos suficientes para permitir que o assistente escreva uma consulta que resolva. Ele vive em algum lugar entre o banco de dados e o assistente, precisa estar em sincronia com um banco de dados que muda por baixo dele e é quase sempre construído no mesmo fim de semana em que a equipe decide que quer um assistente de IA lendo seus dados. Funciona bem para as três primeiras tabelas. Os problemas começam por volta da quarta semana, e nenhum deles se parece com o mesmo problema duas vezes.

A distinção que vale a pena nomear logo é entre a camada de conexão (como o assistente acessa o banco de dados) e a camada de conhecimento (o que o assistente sabe sobre a forma do banco de dados). A camada de conexão recebe a maior parte da atenção, porque credenciais, isolamento de rede e custo de consulta são modos de falha visíveis e fáceis de discutir. A camada de conhecimento é onde a maior parte da qualidade real do assistente reside, e ela se degrada silenciosamente. A página de contexto de banco de dados de IA cobre por que essa segunda camada importa quando a primeira existe.

Por que não apenas apontar o assistente para o banco de dados

Conectar a IA diretamente à produção é o caminho mais curto e o que a maioria das equipes rejeita após cinco minutos de reflexão. O assistente teria acesso de leitura em tabelas que não deveria ver, suas consultas podem ser arbitrariamente caras, suas credenciais viveriam em algum lugar onde não deveriam estar, e a trilha de auditoria se torna difícil de raciocinar. O que a maioria das equipes acaba construindo é uma camada intermediária: uma representação do banco de dados que o assistente pode ler de forma barata e segura, sem nunca tocar na produção.

Essa camada é sobre o que este artigo trata. Não é a conexão. É o catálogo.

As cinco receitas que as equipes constroem

Pergunte a quinze desenvolvedores seniores como construir essa camada e você obterá aproximadamente cinco receitas. A maioria das equipes acaba combinando duas ou três.

Receita 1: o arquivo de catálogo JSON. Um script despeja o esquema (nomes de tabelas, nomes de colunas, tipos) em um arquivo JSON, comprometido no mesmo repositório que a configuração do prompt do assistente. O assistente lê o arquivo na inicialização. A coisa mais simples que funciona.

Receita 2: a atualização noturna. Igual à receita 1, mas um trabalho cron regenera o JSON toda noite a partir do banco de dados em execução. Às vezes sob demanda a partir de um comando slash no Slack.

Receita 3: o servidor MCP personalizado. Um pequeno servidor do Protocolo de Contexto de Modelo fica entre a IA e o banco de dados, expondo um conjunto de consultas tipadas. O assistente chama essas em vez de escrever SQL bruto. O processo MCP mantém as credenciais.

Receita 4: a camada semântica. O catálogo é enriquecido com notas humanas: qual coluna é uma chave estrangeira disfarçada, o que status = 'C' realmente significa neste negócio, quais tabelas estão arquivadas. Esta camada é tipicamente um arquivo YAML ou linhas em uma tabela.

Receita 5: a réplica somente leitura. Uma réplica separada do banco de dados de produção, às vezes com colunas mascaradas, que o assistente pode consultar diretamente. Resolve o problema de credenciais. Não resolve o problema de conhecimento.

Nenhuma dessas é ruim. Todas elas são implementadas. A maioria delas para de funcionar em torno do mesmo ponto da mesma maneira.

Por que todas as cinco receitas funcionam na primeira semana

As receitas entregam a mesma coisa no primeiro dia: o assistente responde a uma pergunta sobre o banco de dados, corretamente, na frente de alguém que queria vê-lo funcionar. A equipe sai com a impressão de que a camada está pronta. A camada não está pronta. A camada está no dia zero de uma linha do tempo de manutenção que ninguém planejou.

Por que todas as cinco receitas começam a falhar por volta da terceira semana

Quatro modos de falha, na ordem em que as equipes geralmente os encontram.

Uma coluna é renomeada e ninguém atualiza o catálogo. Um desenvolvedor renomeia user_email para contact_email em uma migração. A migração é enviada. O arquivo do catálogo ainda diz user_email. O assistente pergunta por user_email e recebe um erro de "coluna não existe", ou pior, silenciosamente recebe zero linhas de volta e relata com confiança "não há usuários com um email".

Uma nova coluna aparece e o assistente nunca aprende sobre ela. A atualização noturna (receita 2) a captura em quinze horas. Nessas quinze horas, o assistente é questionado sobre algo que teria precisado da nova coluna e responde com base na antiga forma do mundo. Sem erro, sem aviso, apenas uma resposta errada entregue com a mesma confiança que uma correta.

As notas semânticas se desincronizam da realidade. O arquivo YAML (receita 4) dizia que status = 'C' significa "cancelado". Alguém mudou para significar "completo" há seis meses como parte de uma reformulação da lógica de negócios. O YAML nunca foi atualizado. O assistente responde perguntas sobre pedidos cancelados com linhas para pedidos completos.

As consultas tipadas do MCP param de corresponder ao esquema. Uma consulta tipada (receita 3) foi escrita para uma tabela com três colunas. A tabela agora tem cinco. A consulta ainda é executada, ainda retorna linhas, e ignora as duas novas colunas completamente. O assistente trabalha em torno de uma limitação fantasma do banco de dados que só existe no código entre os dois.

Nenhum desses modos de falha é exótico. Todos eles aparecem em qualquer banco de dados com mais de um ano, com mais de três desenvolvedores, sem que ninguém faça nada de errado.

Como é uma camada que sobrevive

Três propriedades separam um catálogo que envelhece bem de um que fica obsoleto em duas semanas.

Ele é regenerado a partir do banco de dados em execução em uma programação, não a partir de um arquivo. A fonte da verdade sobre o que o assistente vê deve ser o que o banco de dados atualmente é, não o que alguém escreveu quando construiu a camada. Se a regeneração não for automatizada, não acontecerá. Esta é a diferença entre "o catálogo é código" (frágil) e "o catálogo é uma instantânea" (autocurável). A mecânica de fazer isso bem é discutida em mais detalhes na peça sobre detecção de deriva de esquema.

Ele registra mudanças estruturais como eventos tipados, não como diffs brutos. Quando uma coluna é renomeada, alguém precisa ver "a coluna user_email foi renomeada para contact_email em 2026-08-14" em vez de duzentas linhas de diff unificado entre dois arquivos JSON. Isso é o que torna a deriva legível e revisável, em vez de ruído para rolar para baixo. A página de histórico de mudanças de esquema mostra como isso se parece quando os eventos são tipados e classificados por severidade.

Ele carrega anotações humanas ao lado dos metadados e as versiona. As notas semânticas (quais valores de enumeração significam o quê, quais duas junções de coluna são essenciais, quais tabelas estão arquivadas) vivem ao lado do catálogo bruto, versionadas juntas, para que quando o esquema muda, as anotações sejam sinalizadas para revisão em vez de silenciosamente sobreviverem ao seu referente.

Uma camada com essas três propriedades não é construída em um fim de semana. É por isso que quase ninguém tem uma, e por que a maioria das equipes está rodando um arquivo de catálogo que era preciso há três semanas.

Onde a Taavik se encaixa

A Taavik é uma implementação das três propriedades acima, empacotada como um servidor do Protocolo de Contexto de Modelo (MCP) que assistentes de IA e agentes de codificação consomem diretamente.