Conector Datlas

O conector liga o Datlas Enterprise aos bancos de uma rede privada. Ele roda dentro da rede da empresa, ao lado dos bancos, e só faz conexões de saída para o Datlas. Nenhuma porta aberta, nenhum IP liberado.

Vai pedir para um agente de IA instalar? Passe para ele as instruções para agentes e o token de registro. Elas têm os passos, as verificações e o que ele deve relatar no fim.

Visão geral

Um administrador cria o conector em Console → Conectores e recebe um token de registro (uso único, válido por 24 horas).
O TI roda o contêiner numa máquina que alcança os bancos, com o token e as conexões dos bancos.
O conector se registra, conecta no Datlas e passa a atender as fontes. O status aparece em Console → Fontes.

Segurança

Só saída: um canal TLS (WebSocket) para app.datlasdb.com:443, aberto pelo conector. Nada escuta conexões de entrada.
Identidade própria: na primeira execução o conector cria uma chave Ed25519 e entrega ao Datlas só a parte pública. A cada conexão ele prova quem é assinando um desafio novo.
Comandos assinados: cada comando do Datlas vem assinado, vale 60 segundos e roda uma vez. Cada resposta volta assinada pelo conector.
Senhas ficam na sua rede: as credenciais dos bancos ficam nas variáveis do conector (ou chegam lacradas para ele, que é o único que abre).
Revogação: revogar em Console → Conectores desliga o conector na hora.
Alcance restrito (opcional): DATLAS_ALLOW_HOSTS limita quais bancos ele pode alcançar.

Antes de instalar

Uma máquina com Docker que alcance os bancos. Se os bancos só existem numa VPN ou rede privada, a máquina precisa estar dentro dela.
Saída HTTPS liberada para app.datlasdb.com na porta 443.
O token de registro e os nomes das fontes que o Datlas espera (em Console → Fontes, coluna Conexão: "conector X · fonte qa").
Para cada banco: host, porta, banco, usuário e senha. O usuário é escolha da empresa. Consultas rodam sempre em transação somente leitura. Alterações de dados só acontecem numa fonte em que o console liberou alterações, para quem tem o papel que permite, em transação revisada (COMMIT explícito, confirmação em produção, auditoria). O que cada pessoa vê e faz no Datlas é definido pelas permissões do projeto; o usuário do banco é o limite máximo. Para proibir alterações neste conector, qualquer que seja a configuração do console, use DATLAS_READ_ONLY=true.

Se quiser um usuário só de leitura, por exemplo no PostgreSQL:

CREATE ROLE datlas_reader LOGIN PASSWORD '...';
GRANT CONNECT ON DATABASE nome_do_banco TO datlas_reader;
GRANT USAGE ON SCHEMA public TO datlas_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO datlas_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO datlas_reader;

Instalação

1. Arquivo de configuração

Crie datlas-connector.env com permissão 600. Uma linha por fonte, e a senha na variável _PASSWORD correspondente:

DATLAS_ENROLL_TOKEN=<token do console>
DATLAS_SOURCE_QA=postgresql://usuario@host-qa:5432/banco?sslmode=require
DATLAS_SOURCE_QA_PASSWORD=<senha>
DATLAS_SOURCE_PROD=postgresql://usuario@host-prod:5432/banco?sslmode=require
DATLAS_SOURCE_PROD_PASSWORD=<senha>

2. Subir o conector

docker run -d --name datlas-connector --restart unless-stopped \
  --env-file datlas-connector.env \
  -v datlas-connector:/data \
  -e DATLAS_HEALTH_PORT=8081 \
  ghcr.io/cendyandreoli/datlas-connector:latest

Bancos alcançáveis só pela VPN ou rede privada da máquina: acrescente --network host, para o contêiner usar a mesma rede e o mesmo DNS da máquina.

O volume datlas-connector guarda a identidade do conector. Mantenha-o: apagar o volume exige um novo registro.

Variáveis

Variável	Para quê
`DATLAS_ENROLL_TOKEN`	Registro na primeira execução. Uso único, 24 horas.
`DATLAS_SOURCE_<NOME>`	Conexão de uma fonte: `postgresql://`, `mysql://` ou `mariadb://` usuário@host:porta/banco?sslmode=… O nome vira a fonte em minúsculas (`_` vira `-`).
`DATLAS_SOURCE_<NOME>_PASSWORD`	Senha dessa fonte.
`DATLAS_ALLOW_HOSTS`	Opcional. Hosts ou redes que o conector pode alcançar, ex.: `*.db.suaempresa.com,10.0.0.0/8`.
`DATLAS_HEALTH_PORT`	Opcional. Porta de `/healthz` e `/metrics` (Prometheus).
`DATLAS_CONNECTOR_IDENTITY`	Opcional. Identidade vinda de um cofre de segredos, para réplicas.
`DATLAS_SERVER`	Opcional. Endereço do Datlas, se não for `https://app.datlasdb.com`.

Verificar

docker logs datlas-connector 2>&1 | tail -5
# Conectado ao Datlas (2 fonte(s)).

docker exec datlas-connector python /app/datlas-connector.py check
# prod: ok, 187 tabela(s)
# qa: ok, 187 tabela(s)

Status no console

Em Console → Fontes, a coluna Status mostra o resultado do teste que o Datlas faz em cada fonte a cada minuto (ou na hora, em "Testar conexão agora"):

Status	Significa
Conectada	A fonte respondeu. Mostra o tempo de resposta e quando foi verificada.
Conector offline	O conector dessa fonte não está conectado ao Datlas.
Aguardando conector	O Datlas não alcança o banco e nenhum conector atende a fonte ainda.
Erro	O banco foi alcançado, mas recusou (senha, SSL, banco inexistente…). O motivo aparece embaixo.
Verificando…	Ainda não houve teste desde o cadastro.

Em Console → Conectores aparecem, para cada conector, se está online, a versão, as réplicas e as fontes que ele oferece.

Problemas comuns

O que aparece	O que fazer
Registro recusado: token inválido, já usado ou expirado	Gere um novo em Console → Conectores → "Gerar novo registro".
Logs repetem "Sem conexão com o Datlas"	Libere a saída HTTPS/WebSocket para `app.datlasdb.com:443`.
Erro: a fonte X não está configurada neste conector	Falta a variável `DATLAS_SOURCE_X` com o nome que o Datlas espera.
Erro: o banco recusou usuário ou senha	Confira usuário e senha no arquivo de configuração.
Erro: tempo esgotado ao falar com o banco	A máquina não alcança o banco. Teste com `nc -vz host porta`; em VPN ou rede privada, use `--network host`.

Réplicas (produção)

Gere a identidade uma vez e guarde no cofre de segredos: docker run --rm -e DATLAS_ENROLL_TOKEN=… ghcr.io/cendyandreoli/datlas-connector enroll --print-identity
Suba 2 ou mais réplicas com DATLAS_CONNECTOR_IDENTITY, as variáveis das fontes e DATLAS_HEALTH_PORT=8081.
Para trocar a chave: comando rotate, e atualize o segredo com a nova identidade.

Para agentes de IA

instructions.md: passo a passo em inglês, com verificação, solução de problemas e o que relatar.
llms.txt: índice do Datlas para LLMs.