Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

Updated on 2026-10-04

TimescaleDB — connector

Connects to your TimescaleDB (Postgres) service and extracts tables and hypertables on a schedule. Supports incremental load by time column.

On this page (15)

Leia antes: ../conectores.md (mapa de estados) e fichas.md (índice das fichas).


O que é#

Connects to your TimescaleDB (Postgres) service and extracts tables and hypertables on a schedule. Supports incremental load by time column.

Supported ingestion modes:

  • Nós buscamos — Nós buscamos os dados na sua fonte.

Para que serve#

Bring TimescaleDB data into your datalake and make it available to the Bronze/Silver/Gold layers, BI models and the natural language question wizard.

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 run fica bloqueada.
  • Desligamento: a run 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.
  • Allow two networks at the source: the application server (where Test connection comes from) and the pipeline runner (where the scheduled extraction comes from), which has a different outbound IP.

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#

CampoRótuloTipoObrigatórioObservação
hostEndereço do servidortextosimNome ou IP do servidor do banco. Quem cuida do seu sistema (TI ou fornecedor do ERP) sabe informar.
portPortanúmerosimpadrão: 5432; Já vem com a porta padrão (5432). Só mude se o seu TI disser que é outra.
databaseNome do bancotextosimO nome do banco de dados dentro do servidor.
schemaSchematextonãoOpcional. Deixe vazio para ver todas as tabelas que o usuário enxerga.
userUsuáriotextosimPrefira um usuário só de LEITURA, criado para o BI.
password 🔒Senhasenha/segredosimsegredo (cifrado; cofre externo opcional); Guardada cifrada. Depois de salva, ninguém consegue vê-la de novo — nem você.
sslmodeSegurança da conexão (SSL)seleçãonãopadrão: require; opções: disable / require / verify-ca / verify-full; Deixe em “require” (conexão protegida). Só mude se o seu TI pedir.
networkComo chegamos ao bancoseleçãonãopadrã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.
sshHostHost do bastion (SSH)textonãoaparece quando network = ssh
sshPortPorta do bastionnúmeronãopadrão: 22; aparece quando network = ssh
sshUserUsuário do bastiontextonãoaparece quando network = ssh
sshPrivateKey 🔒Chave privada SSHsenha/segredonãosegredo (cifrado; cofre externo opcional); aparece quando network = ssh

Passo a passo#

  1. No menu Dados → Conexões, use Nova conexão.
  2. Escolha TimescaleDB no catálogo.
  3. Preencha os campos do formulário (veja a tabela acima).
  4. Use Testar conexão. The result is shown broken down into Conectividade, Autenticação and Listagem/leitura — each with OK, Failed, Not applicable or Not tested. A capability with no test of its own for this connector shows as Not applicable, and Not applicable never counts as success.
  5. Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
  6. 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.
  7. 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):

text
# Exemplo sintético (valores fictícios — não são credenciais reais)
host = db.exemplo.invalid
port = 5432
database = vendas
schema = public
user = leitura_bi
password = •••••• (cifrado — nunca exibido)
sslmode = require
network = direct

Resultado 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 run (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).
  • Cost: the extraction itself is not charged by the platform; the Bronze load consumes datalake processing (billable).

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. Check the network mode chosen in How we reach the database. Remember there are two networks: the application server (where Test connection comes from) and the pipeline runner (where the scheduled extraction comes from), with different outbound IPs.
  • Autenticação falhou — usuário/senha inválidos ou usuário sem permissão de leitura no schema.
  • SSL/handshake — adjust Connection security (SSL) (sslmode: disable, require, verify-ca, verify-full) according to the server's requirements.
  • Tabela/consulta grande — a extração respeita o teto de páginas/linhas; use carga incremental por watermark para reduzir o volume.

Troubleshooting#

  • Use Testar conexão para isolar problemas de credencial/rede antes de agendar.
  • Acompanhe as runs 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#


Last revision: 2026-10-04. Card automatically generated from the product connectors catalog.

Related links