Pular para o conteúdo principal
O modelo do Fetcher é pequeno: você registra conexões com bancos de dados externos, o Fetcher descobre seus esquemas, e você submete jobs de extração que produzem resultados assinados e criptografados. Esta página percorre cada peça.

​
Conexões

Uma conexão é uma referência nomeada e armazenada a um banco de dados externo — seu tipo, host, porta, nome do banco e credenciais. O Fetcher suporta cinco tipos de conexão: POSTGRESQL, MYSQL, ORACLE, SQL_SERVER e MONGODB.
  • Credenciais são criptografadas em repouso com AES-256-GCM antes de chegar ao armazenamento; senhas em texto claro nunca persistem.
  • Conexões são testáveis: um endpoint dedicado abre uma conexão real e reporta a latência, permitindo validar a conexão antes que qualquer job dependa dela.
  • Conexões em uso são protegidas: atualizar ou excluir uma conexão com jobs ativos é rejeitado.
Além das conexões registradas pela API, operadores podem definir datasources internos diretamente por variáveis de ambiente (DATASOURCE_{NAME}_*) — útil para bancos fixos, de propriedade da plataforma. Veja Configuração.

​
Descoberta de esquemas

O Fetcher detecta automaticamente tabelas, colunas e tipos de dados nos bancos aos quais se conecta — a mesma descoberta funciona nos cinco tipos de banco. Para bancos relacionais, ele lê o catálogo, incluindo namespaces multi-schema (schemas do PostgreSQL, owners do Oracle, schemas do SQL Server). Para o MongoDB, onde coleções não têm esquema declarado, o Fetcher infere um por amostragem estatística de documentos. Duas coisas se apoiam na descoberta:
  • Validação de esquema: antes de rodar um job, você pode validar que as tabelas e campos que planeja extrair de fato existem nos datasources.
  • Cache de esquemas: esquemas descobertos ficam em cache (com TTL configurável), evitando reintrospectar o banco a cada job repetido.

​
Jobs de extração

Um job é uma solicitação assíncrona de extração de dados. Seu coração é o mapa mappedFields — quais campos, de quais tabelas, de quais datasources: 
{
  "dataRequest": {
    "mappedFields": {
      "meu_postgres": {
        "accounts": ["id", "email", "created_at"]
      },
      "meu_mongo": {
        "transactions": ["*"]
      }
    }
  }
}
  • Projeção de campos: nomeie os campos que quer, ou use ["*"] para todos os campos.
  • Multi-tudo: um único job pode abranger múltiplos datasources, múltiplas tabelas por datasource e múltiplos schemas.
  • Tratamento de JSON: campos JSON/JSONB em bancos relacionais são interpretados automaticamente.

​
Filtros

Jobs podem filtrar linhas por tabela com um conjunto de 10 operadores: eq, ne, gt, gte, lt, lte, between, in, nin e like. 
{
  "dataRequest": {
    "filters": {
      "meu_postgres": {
        "transactions": {
          "status": { "in": ["completed", "pending"] }
        }
      }
    }
  }
}

​
Ciclo de vida do job

StatusSignificado
pendingAceito e enfileirado; ainda não capturado por um Worker
processingUm Worker está extraindo os dados
completedResultados armazenados e evento de conclusão publicado
failedA extração falhou; o evento de falha foi publicado
Jobs são deduplicados: uma solicitação idêntica dentro de uma janela de 5 minutos retorna o job existente em vez de criar um novo. Em estados terminais, o Worker publica eventos de notificação job.completed / job.failed, para que consumidores reajam sem precisar fazer polling.

​
Resultados

O Worker grava os resultados da extração em object storage — SeaweedFS por padrão, ou qualquer serviço compatível com S3:
  • Criptografados em repouso, com TTL de retenção configurável.
  • Assinados: cada documento extraído carrega uma assinatura HMAC-SHA256. Consumidores podem derivar a chave de verificação a partir da chave-mestra e checar a autenticidade do que leem — os dados comprovadamente vieram do Fetcher e não foram adulterados.

​
Serviços e o Engine

Duas formas de implantação compartilham um único núcleo:
  • Serviços standalone — o Manager (API HTTP, metadados no MongoDB, despacho de jobs via RabbitMQ) e o Worker (consumidor de fila, extração, armazenamento de resultados). É a forma que o guia de primeiros passos executa.
  • Engine embarcado — o núcleo de extração (pkg/engine) como um módulo Go importável, com zero dependências de terceiros. Aplicações hospedeiras conectam sua própria infraestrutura às interfaces do Engine e rodam extrações no próprio processo. Sem um armazenamento de resultados, o Engine roda em modo Direct: os resultados voltam inline com um digest de integridade SHA-256.
A regra prática: o Engine é dono de o que extração significa — planejamento, validação, limites, isolamento de tenant; o host (Manager/Worker, ou a sua aplicação) é dono de como ela roda — filas, armazenamento, autenticação, ciclo de vida.

​
Tenancy

O Fetcher roda single-tenant por padrão. Em modo multi-tenant, toda operação é escopada a um tenant resolvido a partir do contexto de tenant baseado em JWT, e cada tenant recebe bancos de metadados, namespaces de cache e caminhos de object storage isolados. Os caminhos de código multi-tenant têm custo zero quando o modo está desabilitado. Veja Multi-tenancy para o modelo da plataforma.

​
Próximos passos

Primeiros passos

Rode o Fetcher localmente e execute seu primeiro job de extração.

Configuração

As variáveis de ambiente que moldam uma implantação do Fetcher.