Estado: Preview — comportamento pode mudar; sem SLA. Métricas de nuvem (custo faturado, latência): NÃO MEDIDO.
Leia antes:
../conectores.md(mapa de estados) efichas.md(índice das fichas).
O que é#
Conecta no seu CockroachDB pelo protocolo PostgreSQL (porta 26257, TLS) e extrai tabelas no agendamento. Suporta carga incremental por watermark.
Modos de ingestão suportados:
- Nós buscamos — Nós buscamos os dados na sua fonte.
Para que serve#
Trazer os dados de CockroachDB para o seu datalake e disponibilizá-los às camadas Bronze/Silver/Gold, aos modelos de BI e ao wizard de perguntas em linguagem natural.
Quando usar / quando não usar#
Use quando você precisa consolidar esta fonte no datalake de forma agendada, com isolamento por workspace.
Evite carga completa desnecessária em tabelas grandes: prefira a carga incremental por watermark (veja Limites e o guia de incremental).
Plano e permissões#
- Plano: núcleo do produto (conectores fazem parte de todos os planos; o limite é o número de fontes do plano).
- Acesso: exige workspace ativo — com a assinatura em atraso, suspensa ou cancelada, a execução fica bloqueada.
- Desligamento: a execução de ingestão pode ser desligada temporariamente (manutenção ou incidente). Quando isso acontece, a tela informa que o recurso está indisponível no momento.
Pré-requisitos#
- Um usuário somente leitura no banco, com acesso ao schema/tabelas desejados.
- Rede: escolha como chegamos até o banco — IP público + allowlist, túnel SSH (bastion), Cloud SQL ou VPN.
- Libere duas redes na origem: o servidor da aplicação (de onde sai o Testar conexão) e o executor dos pipelines (de onde sai a extração agendada), que tem outro IP de saída.
Credenciais#
Campos sensíveis. Eles são cifrados (AES-256-GCM) e nunca ficam no config da conexão, na definição do pipeline, no export ou na DAG. Por padrão o valor cifrado fica no banco; mover a credencial desta conexão para o cofre externo de credenciais é uma escolha explícita, feita por conexão depois de salvar — ver ../../administracao/credenciais-e-rotacao.md.
- Senha (
password) — Guardada cifrada. Depois de salva, ninguém consegue vê-la de novo — nem você. - Chave privada SSH (
sshPrivateKey)
Segredos nunca são reexibidos e passam pela redação em todo erro/log (token cru, URL-encoded e em JSON).
Campos do formulário#
| Campo | Rótulo | Tipo | Obrigatório | Observação |
|---|---|---|---|---|
host | Endereço do servidor | texto | sim | Nome ou IP do servidor do banco. Quem cuida do seu sistema (TI ou fornecedor do ERP) sabe informar. |
port | Porta | número | sim | padrão: 26257; Já vem com a porta padrão (26257). Só mude se o seu TI disser que é outra. |
database | Nome do banco | texto | sim | O nome do banco de dados dentro do servidor. |
schema | Schema | texto | não | Opcional. Deixe vazio para ver todas as tabelas que o usuário enxerga. |
user | Usuário | texto | sim | Prefira um usuário só de LEITURA, criado para o BI. |
password 🔒 | Senha | senha/segredo | sim | segredo (cifrado; cofre externo opcional); Guardada cifrada. Depois de salva, ninguém consegue vê-la de novo — nem você. |
sslmode | Segurança da conexão (SSL) | seleção | não | padrão: require; opções: disable / require / verify-ca / verify-full; Deixe em “require” (conexão protegida). Só mude se o seu TI pedir. |
network | Como chegamos ao banco | seleção | não | padrão: direct; opções: direct / ssh / cloudsql / vpn; Na maioria dos casos é “direto pela internet”. Use túnel SSH se o banco só aceita acesso pela rede interna. |
sshHost | Host do bastion (SSH) | texto | não | aparece quando network = ssh |
sshPort | Porta do bastion | número | não | padrão: 22; aparece quando network = ssh |
sshUser | Usuário do bastion | texto | não | aparece quando network = ssh |
sshPrivateKey 🔒 | Chave privada SSH | senha/segredo | não | segredo (cifrado; cofre externo opcional); aparece quando network = ssh |
Passo a passo#
- No menu Dados → Conexões, use Nova conexão.
- Escolha CockroachDB no catálogo.
- Preencha os campos do formulário (veja a tabela acima).
- Use Testar conexão. O resultado vem separado em Conectividade, Autenticação e Listagem/leitura — cada um com OK, Falhou, Não se aplica ou Não testado. Capacidade sem teste próprio para este conector aparece como Não se aplica, e Não se aplica nunca conta como sucesso.
- Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
- No cartão da conexão, use Montar extração (ou vá em Orquestração → Pipelines e use Conectar fonte). O pipeline aponta para a conexão salva — a credencial não é copiada.
- Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.
Exemplo — teste de conexão#
Configuração de exemplo (todos os valores são fictícios; segredos aparecem mascarados):
# Exemplo sintético (valores fictícios — não são credenciais reais)
host = db.exemplo.invalid
port = 26257
database = vendas
schema = public
user = leitura_bi
password = •••••• (cifrado — nunca exibido)
sslmode = require
network = directResultado esperado#
O Testar conexão retorna a lista de tabelas/recursos descobertos. Após a primeira carga, as linhas aparecem na camada Bronze do seu workspace, prontas para o pipeline.
Limites e custos#
- Paginação: teto duro por execução (default 10.000 páginas / 5.000.000 linhas); guarda anti-loop.
- Incremental por watermark: append/keyset por coluna-chave. Não é CDC — não captura deletes nem UPDATEs fora da janela do watermark. CDC verdadeiro (WAL/redo/binlog) está no Roadmap.
- Volume estimado: ~5 GB/mês (estimativa de catálogo, não medição).
- Custo: a extração em si não é cobrada pela plataforma; a carga Bronze consome processamento do datalake (cobrável). Custo faturado real de nuvem = NÃO MEDIDO.
Segurança#
- Escopo por workspace: cada cliente lê e escreve só no seu próprio datalake (
<prefixo>_bronze/_silver/_gold); nunca há vazamento entre workspaces. - Segredos cifrados: material sensível é cifrado com AES-256-GCM antes de ser gravado. O cofre externo de credenciais é opcional e ligado por conexão; sem ele, o valor cifrado fica no banco. Trocar o valor aqui NÃO revoga a credencial na origem.
- Redaction: todo erro/log passa pela redação de segredos (cru, URL-encoded e em JSON).
- Produção não finge: um caminho que cairia em mock aciona a guarda de produção (falha explícita em vez de simular sucesso).
Erros comuns#
- Conexão recusada / timeout — host, porta ou regra de rede (allowlist/SSH/VPN) incorretos. Confira o modo de rede escolhido em Como chegamos ao banco. Lembre que são duas redes: o servidor da aplicação (de onde sai o Testar conexão) e o executor dos pipelines (de onde sai a extração agendada), com IPs de saída diferentes.
- Autenticação falhou — usuário/senha inválidos ou usuário sem permissão de leitura no schema.
- SSL/handshake — ajuste Segurança da conexão (SSL) (
sslmode:disable,require,verify-ca,verify-full) conforme a exigência do servidor. - Tabela/consulta grande — a extração respeita o teto de páginas/linhas; use carga incremental por watermark para reduzir o volume.
Diagnóstico#
- Use Testar conexão para isolar problemas de credencial/rede antes de agendar.
- Acompanhe as execuções na observabilidade por conector (taxa de erro, p50/p95, freshness).
- Uma mudança de esquema na origem é sinalizada pelo schema drift (coluna nova = info; coluna removida/tipo mudado = atenção).
Relacionados#
../conectores.md— catálogo de conectores por estado../ingestao-incremental-backfill.md— full, incremental por watermark, backfill e checkpoint../pipeline-medalhao.md— camadas Bronze/Silver/Gold e qualidade../agendamento-retry-dlq.md— agendamento, retry/backoff e DLQ../custo-limites-seguranca.md— custo, tetos e segurança por workspace
Última revisão: 2026-10-04. Ficha gerada automaticamente do catálogo de conectores do produto.