Conectores de banco

Esta página é para quem cuida do banco de dados da sua operação. Um conector de banco deixa a investigação automática conferir fato no seu banco em vez de adivinhar — e faz isso dentro de cercas que você define tabela por tabela e coluna por coluna.

Se você é o dono da operação e não mexe com banco, mande esta página para quem mexe. Ela é a parte da instalação em que uma decisão errada custa caro.

O que o conector pode e o que não pode

O conector é somente leitura, e a leitura é cercada em quatro camadas:

1. Só SELECT. A consulta que o modelo escreve é lida por um analisador que monta a árvore sintática do comando. INSERT, UPDATE, DELETE, MERGE, CREATE, DROP, ALTER, TRUNCATE, GRANT, LOCK e comandos de transação são rejeitados. Duas consultas numa chamada só: rejeitado. Funções perigosas (pg_sleep, pg_read_file, dblink, load_file, benchmark, sys_exec e companhia) estão numa lista de bloqueio.
2. Lista branca de tabelas. Toda tabela citada — inclusive dentro de subconsulta, CTE ou junção — precisa estar na lista que você marcou. Fora da lista, a consulta é recusada.
3. Colunas mascaradas. Uma coluna marcada como mascarada não pode nem ser citada: a consulta que a menciona é recusada antes de rodar. E se ela aparecer num SELECT *, o valor volta como ***MASKED***.
4. Sessão somente-leitura no próprio banco. A conexão abre com default_transaction_read_only=on no PostgreSQL, ou SET SESSION TRANSACTION READ ONLY no MySQL, mais um timeout de 5 segundos por comando.

Depois de tudo isso, a consulta é reescrita a partir da árvore sintática antes de ir para o banco. Comentário nenhum sobrevive à reescrita — inclusive os comentários executáveis do MySQL, que são um caminho clássico de contorno.

Bom saber: o conselho que a própria tela dá é o certo: aponte para uma réplica de leitura e crie um usuário de banco com permissão só de SELECT. As cercas do ChatMade são uma segunda camada, não a única.

Bancos suportados

PostgreSQL e MySQL. Não há conector para SQL Server, Oracle, BigQuery, Snowflake ou MongoDB.

Passo a passo

1. Abra a tela

No painel, vá em Settings → Ticketing (“Configurações → Chamados”). Role até a seção “Database connector” (“Conector de banco”), marcada com a etiqueta “Read-only — the AI can never write” (“Somente leitura — a IA nunca escreve”).

Clique em ＋ Connect a database (“Conectar um banco”).

2. Preencha a conexão

Campo na tela	O que colocar
Name (“Nome”)	Como você vai reconhecer esse conector na lista. Ex.: Réplica de produção
Engine (“Banco”)	PostgreSQL ou MySQL
Host	O endereço do banco
Port (“Porta”)	Vem 5432 e muda sozinho para 3306 quando você escolhe MySQL
Database (“Base”)	O nome da base
Username (“Usuário”)	O usuário somente-leitura que você criou
Password (“Senha”)	Guardada criptografada; nunca volta para a tela
Max rows per query (“Máximo de linhas por consulta”)	Vem 100. Aceita de 1 a 1000

O teto de linhas é aplicado três vezes: o LIMIT é injetado ou reduzido na própria consulta, a leitura busca no máximo esse número mais um, e a tabela de resultado é cortada no número exato, anotando (N rows, truncated).

3. Se o banco está atrás de um bastion, ligue o túnel SSH

Marque “Connect through an SSH tunnel” (“Conectar por um túnel SSH”). O host e a porta que você preencheu acima passam a ser resolvidos de dentro da rede do host SSH.

Campos: SSH host, SSH port (vem 22), SSH username, e em Authentication (“Autenticação”) você escolhe entre Private key (“Chave privada”) e Password (“Senha”). Escolhendo chave, cola em Private key (PEM / OpenSSH) e, se ela tiver senha, em Key passphrase (optional) (“Senha da chave (opcional)”).

Os quatro segredos — senha do banco, senha do SSH, chave privada e senha da chave — ficam criptografados no banco e nunca são devolvidos pela API.

4. Teste a conexão

Clique em Test connection (“Testar conexão”). O botão vira Connecting… (“Conectando…”) e, dando certo, aparece a linha “{n} tables discovered — select what the AI may query” (“{n} tabelas encontradas — escolha o que a IA pode consultar”).

Se você já testou uma vez, o botão passa a se chamar Re-test connection (“Testar de novo”). Dando errado, o motivo aparece ali mesmo.

As credenciais desse primeiro teste são usadas uma vez e não são gravadas — só viram conector quando você salva.

5. Marque as tabelas

Depois do teste, a lista de tabelas aparece agrupada por schema, com a contagem de colunas de cada uma. Marque só o que a investigação precisa ler. Schemas de sistema (pg_catalog, information_schema, pg_toast, mysql, performance_schema, sys) não aparecem.

Se você não marcar nenhuma tabela, o salvamento é recusado: sem tabela na lista, não há nada consultável.

6. Mascare as colunas sensíveis

Em cada tabela marcada, o botão Column masking (“Mascarar colunas”) abre a lista de colunas. Cada coluna tem uma pastilha que alterna entre Visible (“Visível”) e Masked (“Mascarada”).

O mascaramento vale por nome de coluna, em todo o conector — mascarou cpf numa tabela, cpf está mascarado em todas.

Consulta que cita uma coluna mascarada é recusada. E as saídas de contorno estão fechadas: expandir a linha inteira (t.* dentro de uma expressão, ou uma referência à linha como um todo) é bloqueado enquanto houver coluna mascarada na tabela. SELECT * como projeção continua permitido, e o valor mascarado volta como ***MASKED***.

7. Amarre as linhas ao cliente do chamado

Esta é a parte que mais importa e a que mais gente esquece.

Em cada tabela, o campo “Restrict to the ticket’s customer” (“Restringir ao cliente do chamado”) deixa você apontar a coluna que guarda a identidade do cliente. A opção vazia é “Not restricted — all rows readable” (“Sem restrição — todas as linhas legíveis”).

Escolhida a coluna, o ChatMade reescreve a consulta trocando a tabela por uma subconsulta já filtrada. O modelo não filtra — ele recebe uma tabela que já só tem as linhas daquele cliente, e não tem como alargar isso.

Com pelo menos uma tabela amarrada, aparece o seletor “Match the customer by” (“Casar o cliente por”), com Email address (“Endereço de e-mail”) ou Phone number (“Número de telefone”). O e-mail é comparado ignorando maiúsculas e minúsculas; o telefone é comparado exatamente, então guarde no mesmo formato dos dois lados.

Atenção: a regra falha fechada. Se o chamado não tem cliente identificado, a consulta a uma tabela amarrada é recusada com um recado explícito, em vez de devolver a base inteira. Deixe sem restrição só tabelas que não pertencem a ninguém em particular — tabela de referência, catálogo, feriado, faixa de CEP.

8. Salve

Save connector (“Salvar conector”). Na lista, o conector aparece com o nome, o banco em maiúsculas, uma etiqueta connected ou connection failed, e a linha de resumo {usuário}@{host}:{porta}/{base} · {n} tables allowed · {n} masked columns · {n} customer-scoped.

A caixa Active (“Ativo”) liga e desliga o conector sem apagá-lo. Edit tables (“Editar tabelas”) volta para a lista branca; Delete (“Excluir”) remove — e a confirmação diz o que isso significa: a IA perde esse acesso.

Auditoria das consultas

Toda consulta que passa pelo conector gera uma linha de auditoria, com três desfechos possíveis: permitida, bloqueada (com o motivo) ou erro. Ficam registrados o SQL que o modelo escreveu, o SQL canônico que de fato rodou, a quantidade de linhas e a duração. O resultado da consulta nunca é gravado na auditoria.

Atenção: essa auditoria não tem tela nem endpoint de leitura. É registro em banco, na tabela db_connector_audit_logs — para conferir, é preciso consultar o banco direto. O que você vê no painel é outra coisa: a evidência por chamada de ferramenta, dentro do painel de investigação de cada chamado.

Quem pode configurar

A tela Settings → Ticketing exige a permissão manage_organization. Existe também a permissão manage_ticket_connectors, e a API aceita as duas — mas o painel esconde a tela de quem só tem a segunda. Na prática, hoje, quem configura conector precisa de manage_organization.

Conectores MCP: uma lista separada, de propósito

Além do banco, a investigação pode usar servidores MCP — Grafana, Elasticsearch, Sentry, CloudWatch ou qualquer outro. Eles ficam na seção “Investigation connectors” (“Conectores de investigação”), na mesma tela.

Essa lista é deliberadamente separada da lista de ferramentas MCP do agente que conversa com o cliente. Uma ferramenta de observabilidade que você liga na investigação nunca chega ao agente de chat, e vice-versa. As duas listas bebem do mesmo inventário de servidores MCP da organização, mas as seleções não se encostam.

Próximo passo

Com o conector no ar, leia Investigação automática para entender o orçamento de cada investigação e os três níveis de autonomia.