Drivers JDBC — Catálogo Oficial e Governança

Baixar driver de banco em site duvidoso, descobrir a incompatibilidade só em produção e nunca saber se aquele JAR carrega uma vulnerabilidade conhecida: esse era o custo invisível de conectar cada fonte nova. O DATTA elimina esse risco com um catálogo oficial de 39 drivers JDBC e uma esteira de validação de segurança pela qual todo JAR passa — baixado automaticamente ou enviado por você — antes de ficar disponível para qualquer conexão.

A gestão fica em Sistema›Drivers JDBC, restrita a administradores. Este guia cobre suas responsabilidades sobre o catálogo: instalação inicial, envio manual, validação, ciclo de vida e monitoramento.

Quem faz o quê

A plataforma não faz mais bootstrap automático no backend — toda a inicialização foi movida para o setup-datta.sh (commit 277661e, "refactor: move all initial setup from backend to setup-datta.sh"). Uma vez instalados, os drivers passam a ser gerenciados em runtime pela tela e pela API de administração.

O que já vem no catálogo (39 drivers)

• Relacionais open-source: PostgreSQL, MySQL, MariaDB, SQLite, H2, HSQLDB, Apache Derby, CockroachDB (usa o driver PostgreSQL) e TimescaleDB (idem).
• Analíticos / colunares: DuckDB, ClickHouse, Apache Druid (via Avatica), Apache Pinot, Apache Doris e StarRocks (ambos compatíveis com MySQL).
• Data warehouse / nuvem: Snowflake, Amazon Redshift, Azure Synapse (compatível com SQL Server), Databricks (download manual), IBM Db2.
• Enterprise: Oracle (manual), Microsoft SQL Server, SAP HANA, Teradata (manual), IBM Informix (manual), SAP ASE jConnect (manual), Firebird (Jaybird), Vertica, Exasol.
• Query engines: Trino, PrestoDB, Apache Spark Thrift (via Hive JDBC), Apache Hive, Apache Impala (Cloudera, manual), Apache Phoenix, Apache Drill.
• Séries temporais: QuestDB (compatível com PostgreSQL), Apache IoTDB, InfluxDB 3.x (via Flight SQL).

São 39 entradas no catálogo oficial, versionado por uma tag de versão que o desenvolvedor incrementa a cada mudança estrutural (campo novo, troca de licença).

Dialetos SQL: você escreve uma vez, a plataforma traduz

Cada driver do catálogo tem um dialeto correspondente registrado na biblioteca de dialetos da plataforma — hoje 39 dialetos, alguns compartilhados (CockroachDB reaproveita o do PostgreSQL, Synapse o do SQL Server). O dialeto absorve as diferenças de cada fornecedor:

• introspecção de catálogo (ALL_TABLES contra information_schema);
• sensibilidade a maiúsculas (Oracle trabalha em caixa alta);
• aspas em identificadores;
• paginação (LIMIT/OFFSET, FETCH ou ROWNUM);
• tipos de data (TIMESTAMP, DATETIME2, TIMESTAMPTZ);
• sintaxe de MERGE/UPSERT.

Regra de arquitetura: lógica específica de fornecedor mora no dialeto e em nenhum outro lugar.

Instalação inicial (Fase 7 do setup-datta.sh)

Quando o operador roda ./setup-datta.sh, a Fase 7 — "Download e upload dos drivers JDBC oficiais" — faz, em sequência:

1. Autentica como administrador para obter as credenciais da sessão.
2. Para cada driver do catálogo que não seja alias nem exija download manual: baixa o JAR da URL oficial do fornecedor para o diretório de logs da instalação e o envia à plataforma junto dos metadados (chave, versão, fornecedor). O endpoint de envio de driver está descrito na referência de API.
3. A esteira de validação roda na hora; passando, o driver é registrado como Pendente e aguarda a sua aprovação. A exceção é o driver Neo4j JDBC, que a instalação aprova em seguida pelo catálogo oficial quando o scan de vulnerabilidades conclui sem achado bloqueante (seção Instalação pelo catálogo oficial). Se ele ficar pendente, a instalação termina com o aviso "driver Neo4j JDBC pendente de aprovação" e os Agentes de Banco de exemplo sobre o CNPJ não são registrados: aprove o driver (Revalidar e Aprovar) e rode de novo o registro dos agentes que o aviso indica.
4. Drivers de licença click-through são pulados com aviso — cabe a você baixá-los e enviá-los pela tela (próxima seção).

A flag --skip-drivers pula a Fase 7 inteira: use quando precisar rodar o setup de novo sem refazer os downloads.

Download manual: drivers com licença click-through

Alguns fornecedores exigem aceite explícito de licença no próprio site. Para esses, o download automático é pulado e o driver aparece na tabela com a badge Download manual e link direto para a página oficial:

Passo a passo: enviando o driver Oracle

1. Abra a página oficial pelo link da linha do driver e baixe o JAR, aceitando a licença OTN.
2. Em Sistema›Drivers JDBC, clique em Adicionar driver.
3. Selecione o arquivo .jar e informe nome, fornecedor, versão e a classe do driver.
4. Confirme o envio. A esteira de validação roda na hora; passando, o driver entra como Pendente. Confira o resultado no detalhe do driver e clique em Aprovar: a partir daí ele pode ser usado em novas conexões.

Se o mesmo JAR já tiver sido enviado antes, a plataforma reconhece pelo hash SHA-256 e reaproveita o registro existente, sem criar duplicata — o evento fica registrado como DRIVER.UPLOAD_DEDUP.

Validação de segurança: nenhum JAR entra sem passar pela esteira

Todo JAR — vindo do setup ou enviado por você — atravessa cinco etapas em sequência:

1. Análise estática de bytecode: classes com chamadas perigosas (Runtime.exec, ProcessBuilder, System.loadLibrary) são rejeitadas, assim como JARs pequenos demais para serem um driver real.
2. Varredura de vulnerabilidades contra a base local de CVEs (Trivy / Grype): achado HIGH ou CRITICAL não mitigado bloqueia o driver.
3. Verificação de assinatura digital, quando o fornecedor publica .asc ou hash .sha256.
4. Teste de carga isolado: a classe do driver é carregada em um carregador de classes isolado, para garantir que ela sobe sem exceção não tratada antes de qualquer conexão real.
5. Extração segura do JAR e inferência de metadados, que completam a ficha do driver.

Falhou em qualquer etapa? O resultado da validação é registrado com o motivo e o driver vai para Quarentena — nunca fica exposto para uso.

Quando o scan de vulnerabilidades não conclui

O scan pode não concluir: a ferramenta de varredura não está disponível, a base de CVEs não pôde ser baixada, a varredura foi interrompida ou devolveu um relatório fora do formato esperado. Isso não é tratado como scan limpo:

• o driver fica Pendente, com um aviso da etapa de varredura no resultado da validação, e nunca é aprovado automaticamente;
• a severidade registrada no driver é SCAN_FAILED ("sem scan"), sem contagem de CVEs nem data de varredura;
• um Revalidar que também não conclui fica registrado como tentativa no relatório de CVEs do driver, mas não apaga o último resultado válido: um driver com CVE crítico continua mostrando o crítico.

Para liberar o driver, clique em Revalidar no detalhe dele; com o scan válido e sem achado bloqueante, clique em Aprovar.

Instalação sem internet. Na instalação a partir do pacote offline, a base de CVEs não vai junto e a varredura não tem de onde baixá-la: todo scan termina sem concluir, e o Revalidar não resolve. Nesse modo, só a aprovação manual (Aprovar) tira um driver de Pendente — confira o JAR antes, porque a plataforma não conseguiu varrê-lo.

Prazo da varredura e fila de uma varredura por vez

Cada varredura de vulnerabilidades tem prazo de 180 segundos. Esse valor foi medido: a primeira varredura depois de o serviço de drivers reiniciar baixa a base de CVEs e leva cerca de 50 segundos no perfil on-premises e cerca de 100 segundos no perfil mínimo (meio núcleo e 1 GB de memória); com a base já baixada, a varredura leva poucos segundos. Uma varredura que passa do prazo é encerrada e conta como scan que não concluiu (seção anterior), com o aviso "A varredura de vulnerabilidades excedeu o prazo de 180 s".

A base de CVEs fica num volume temporário próprio do serviço de drivers, com teto de 4 GB, fora do volume dos JARs e, portanto, fora do backup dos drivers. Ela sobrevive a um reinício do serviço, mas não à recriação dele: depois de uma publicação de versão, a primeira varredura volta a baixá-la.

Só uma varredura roda por vez. Envios, Revalidar e a instalação pelo catálogo entram numa fila, na ordem de chegada; o download e as demais etapas da esteira continuam em paralelo. Quem espera tempo demais na fila recebe a mensagem "O verificador de vulnerabilidades está ocupado. Tente novamente em alguns minutos." Nesse caso nada é gravado: o envio não cria o driver, o Revalidar não muda o relatório nem o status, e a instalação pelo catálogo marca a entrada como falha, que volta a ser tentada na próxima instalação. Um driver nunca fica Pendente por causa da fila.

Como ler a coluna Segurança

A coluna Segurança da lista de drivers e o cabeçalho do detalhe mostram o resumo da última varredura válida do driver:

A aba Segurança do detalhe lista os CVEs da última varredura válida, com o identificador, o componente afetado, o resumo e a versão que corrige, e mostra no título o scanner e a versão dele (por exemplo, trivy 0.56.2). Quando a aba diz "Lista de CVEs ainda não registrada — use Revalidar", o driver tem o resumo (a coluna mostra a severidade e a contagem), mas a lista detalhada ainda não foi gravada: é o caso dos drivers varridos antes desta versão da plataforma. Um Revalidar grava a lista. Essa mensagem nunca significa "nenhum CVE".

Os achados da análise estática e das demais etapas da esteira não ficam guardados: a aba os mostra depois de um Revalidar, até você fechar o detalhe. Ao terminar, o Revalidar avisa a severidade e a contagem encontradas, ou que a varredura não pôde rodar porque o JAR não pôde ser analisado.

Ciclo de vida e governança

Os quatro status

Driver enviado por você que passa na validação entra como Pendente e só é usado depois de Aprovar; falha de validação vai direto para Quarentena. O filtro de status da lista mostra cada grupo: escolha "Pendentes" para ver o que aguarda aprovação, ou "Todos os status" para ver todos os drivers.

Instalação pelo catálogo oficial

O botão Popular drivers oficiais (e o botão Instalar de cada cartão do catálogo) baixa o JAR do fornecedor, passa pela mesma esteira e aprova o driver automaticamente só quando tudo isto vale:

• a validação não registrou erro;
• o JAR é assinado, quando a política da plataforma exige assinatura;
• o scan de vulnerabilidades concluiu;
• o scan não achou CVE de severidade bloqueante.

Faltando qualquer um deles, o driver fica Pendente, o cartão do catálogo mostra Aguardando aprovação em vez de "Instalado", e o log da instalação explica o motivo. Se o JAR baixado já estava registrado como Pendente (por exemplo, enviado antes pela tela), a plataforma o varre de novo antes de decidir, com a mesma regra — nunca aprova com base num resultado antigo.

Um driver do catálogo que ficou Pendente não é reavaliado por um novo Popular drivers oficiais: para a instalação ele já está instalado. Para liberá-lo, abra-o pelo filtro "Pendentes", clique em Revalidar e, com o scan válido, em Aprovar.

Driver Descontinuado é decisão sua e é respeitado: o Popular drivers oficiais não o reinstala (o log registra skipped_deprecated) e nunca o devolve a Aprovado. Se o arquivo do driver sumiu do armazenamento, a instalação o repõe, e o driver continua descontinuado.

Roda uma instalação pelo catálogo por vez. Enquanto uma está em andamento, um novo Popular drivers oficiais, Instalar ou Atualizar (nesta ou em outra aba) mostra "Já existe um bootstrap de drivers em andamento. Aguarde a conclusão." e não começa. Fechar a aba interrompe a instalação em curso; espere alguns instantes antes de repetir.

Selos do cartão do catálogo

Cada cartão de "Drivers oficiais disponíveis" mostra um selo, avaliado nesta ordem (vale o primeiro que se aplica):

Reinstalar baixa o JAR de novo e o repõe no driver que já existe, sem mudar o status: um driver descontinuado continua descontinuado. O cartão de um driver descontinuado não tem botão de propósito — voltar a usá-lo é decisão sua, com Reativar no detalhe do driver, e fica na auditoria. Atualizar instala a versão nova do catálogo como um driver novo, sem tocar no antigo.

O número de "instalados" no topo do catálogo conta só os cartões com Instalado: drivers descontinuados ou sem arquivo não entram nele.

Ações do administrador

Documentação do fornecedor para o Copilot

A plataforma reindexa a documentação do fabricante de cada driver para alimentar as respostas sobre a fonte. A ingestão roda em segundo plano: o pedido responde na hora e o progresso é consultado em seguida (RUNNING / COMPLETED / FAILED) — os dois endpoints estão na referência de API. O rastreamento baixa as páginas de um mesmo nível em paralelo, controlado por datta.doc-ingest.crawl-concurrency (padrão 6), com teto global de tempo em datta.doc-ingest.crawl-timeout-seconds (padrão 120).

Trilha de auditoria

Toda ação de governança emite evento:

Onde o JAR fica guardado

O arquivo do driver vive num volume persistente próprio (datta-drivers-pvc, 5 GB por padrão), separado do registro do driver. São duas coisas distintas: o registro guarda nome, versão, hash e status; o arquivo é o que os serviços baixam para executar consultas.

Se esse volume for efêmero, o sintoma aparece longe da causa: depois de qualquer reinício — e toda publicação de versão é um reinício — o catálogo continua mostrando os drivers como aprovados, e toda consulta de Agente de Banco falha com Download falhou (HTTP 404) para driver <id>. Enviar o arquivo de novo resolve até a próxima publicação.

Com mais de uma réplica do serviço de drivers, o volume precisa aceitar escrita e leitura simultâneas (ReadWriteMany): uma réplica grava o arquivo enviado e todas as outras precisam lê-lo.

Monitoramento

O serviço de drivers publica a métrica datta.drivers.varredura.duracao: duração de cada varredura de vulnerabilidades, incluindo a espera na fila, com o desfecho na tag outcome — ok (a varredura concluiu), timeout (passou do prazo), falha (não concluiu por outro motivo) e ocupado (desistiu da fila). A latência das demais etapas da esteira aparece nas métricas de requisição HTTP do serviço.

Quatro sinais merecem alerta:

Fontes nativas ficam fora do catálogo JDBC

Fontes com capacidades que um driver JDBC genérico não alcança usam conectores nativos do motor de execução da plataforma — de propósito. Empacotar um wrapper JDBC para elas seria trocar o melhor de cada engine por um mínimo denominador comum:

Drivers JDBC para essas fontes não entram no catálogo oficial.

Exceção nomeada — Neo4j (Cypher, somente-leitura). O driver JDBC oficial do Neo4j voltou ao catálogo para um único uso: o Agente de Banco de exemplo que consulta o cadastro CNPJ carregado na própria plataforma, em Cypher e em sessão de leitura. A entrada é estreita de propósito — tradução SQL desligada, sem GDS, escrita recusada — e não é o caminho de integração de dados com o Neo4j, que continua sendo o conector nativo. Veja Agentes de Banco de Dados no guia do usuário.

Para desenvolvedores: adicionar um driver ao catálogo

Incluir um driver novo no catálogo oficial é mudança de código, feita na lista oficial de drivers da plataforma:

1. Declare a entrada com a chave do driver.
2. Preencha nome, fornecedor, versão, classe do driver, página de origem, URL da documentação, tipo de licença, exemplo de URL JDBC, porta padrão e tags.
3. Se o JAR puder ser baixado direto (Maven Central, por exemplo), informe a URL de download; quando o fornecedor publica .sha256, registre o hash esperado.
4. Licença click-through: marque o driver como de download manual e como exigindo aceite de licença.
5. Alias: aponte para a chave base (CockroachDB aponta para postgresql).
6. Registre o dialeto correspondente na biblioteca de dialetos, se ainda não existir.
7. Incremente a tag de versão do catálogo.
8. Ajuste a Fase 7 do setup-datta.sh apenas se o driver exigir tratamento especial — o laço genérico cobre o caso normal.
9. Sempre que possível, adicione um teste da esteira de validação.

Allowlist de hosts do download pelo catálogo

Quando um driver do catálogo é baixado pela plataforma (bootstrap do catálogo pela API de administração), o download só é aceito por HTTPS e de um host listado em datta.drivers.bootstrap.allowed-hosts, no application.yml do serviço de drivers. A comparação ignora maiúsculas, e o bootstrap não segue redirecionamento: uma URL que responde 3xx falha. No boot, o log do serviço informa quantos hosts foram carregados; lista vazia gera um aviso e desliga a checagem de host.

Para ampliar a lista, inclua o host do fornecedor no application.yml na mesma mudança que adiciona o driver: o teste do catálogo reprova o build quando um download direto usa host fora dela. Também é possível definir a variável de ambiente DATTA_DRIVERS_BOOTSTRAP_ALLOWEDHOSTS (hosts separados por vírgula), mas ela substitui a lista inteira em vez de somar: repita todos os hosts, inclusive repo1.maven.org.

Referências

• Runbook de streaming (Kafka/Debezium): Runbook — Streaming (F9).
• Operação das conexões, incluindo backup e reencriptação de credenciais: Runbook — Gestão de Conexões.
• Endpoints de catálogo, envio e documentação de drivers: referência de API.