A falha de conectividade Oracle mais comum não é um problema de credenciais nem uma regra de firewall. É uma incompatibilidade de driver. Uma IDE que usa um driver JDBC em Thin mode falha silenciosamente ao tentar negociar o handshake com um banco 11g. Uma ferramenta que empacota o node-oracledb em Thin mode simplesmente não consegue alcançar nada anterior ao Oracle 12.1. O desenvolvedor fica olhando para ORA-12541: TNS: no listener ou um timeout sem mensagem, e passa a tarde suspeitando da camada errada.

A Veesker adota uma posição diferente: empacotar o Oracle Instant Client correto, sempre inicializar o Thick mode e deixar a biblioteca OCI cuidar do resto. Este post explica o que isso significa na prática, como funciona a descoberta automática e por que o espectro de versões de 9.2 a 26ai é um problema resolvido quando você assume a arquitetura certa.

Thin mode e Thick mode: a diferença real

Os drivers oficiais da Oracle — incluindo as versões atuais de node-oracledb, python-oracledb e JDBC — oferecem dois modos de operação.

Thin mode é uma reimplementação pura do protocolo de rede. Sem biblioteca nativa, funciona como dependência de pacote padrão em qualquer ambiente com npm ou pip. O custo é que essa reimplementação tem como alvo o protocolo de wire moderno do Oracle. No momento em que este texto foi escrito, o Thin mode do node-oracledb suporta Oracle Database 12.1 em diante. As instalações em 9.2, 10g e 11g que ainda sustentam parcelas significativas do parque Oracle corporativo simplesmente não são alcançáveis em Thin mode.

Thick mode usa a Oracle Call Interface (OCI): uma biblioteca C que a Oracle mantém — e mantém compatível com versões anteriores — há décadas. Quando o driver inicializa o Thick mode, a biblioteca OCI assume a negociação do protocolo de wire com o servidor. O Oracle Instant Client 21c e posteriores conseguem conectar ao Oracle Database 9.2. A janela de compatibilidade abrange todas as versões do Oracle que ainda recebem patches de kernel ou para as quais alguém ainda paga contas.

O motivo pelo qual o Thin mode não cobre esse espectro não é descuido dos mantenedores do driver. Reimplementar completamente um protocolo de wire que acumulou mais de vinte anos de extensões de retrocompatibilidade não é uma tarefa de uma sprint. O Thick mode delega essa complexidade à própria biblioteca da Oracle, que carrega a obrigação de preservá-la.

Empacotando o Instant Client: o que a Veesker de fato entrega

Uma configuração padrão de Thick mode exige que o usuário instale o Oracle Client ou o Instant Client separadamente — uma instalação completa no Windows, ou a extração manual do ZIP BasicLite no macOS e Linux, seguida de atualização de PATH, LD_LIBRARY_PATH ou DYLD_LIBRARY_PATH. Essa é uma operação razoável para um DBA Oracle experiente. É um atrito significativo para o desenvolvedor que quer abrir uma conexão com um sistema novo sem precisar de meio dia de instalação.

A Veesker empacota as bibliotecas do Instant Client diretamente dentro do pacote da aplicação. Na primeira execução, o binário resolve o caminho das bibliotecas para esse local empacotado e chama a rotina de inicialização do OCI antes que qualquer conexão seja tentada. A partir daí, toda conexão da sessão roda em Thick mode automaticamente.

Nenhuma configuração manual é necessária. Nenhuma variável de ambiente ORACLE_HOME. Nenhum tnsnames.ora em diretório de sistema. As bibliotecas ficam no mesmo local que o executável da Veesker, o caminho é resolvido na inicialização, e a conexão funciona.

O cliente empacotado é a versão atual do Oracle Instant Client, que cobre os recursos do 26ai em novas conexões e mantém a retrocompatibilidade total do OCI para servidores legados. Isso não é uma decisão de design da Veesker; é o contrato que a Oracle entrega com cada release do Instant Client.

O handshake de versão e o que a Veesker lê dele

Depois que o OCI negocia a sessão, o Oracle devolve a versão do servidor no pacote de conexão. A Veesker lê essa string de versão imediatamente após o estabelecimento da conexão e a associa ao objeto de conexão. Uma string como 11.2.0.4.0, 19.23.0.0.0 ou 23.7.0.0.0 se torna a fonte única de verdade para tudo que acontece naquela sessão.

Dois comportamentos se ramificam a partir dessa versão.

Controle de funcionalidades na interface. O Oracle 12c introduziu os Pluggable Databases. A árvore de objetos da Veesker mostra a raiz CDB e a lista de PDBs no 12c e posteriores; no 11g e anteriores, essa camada simplesmente não aparece, porque o servidor não tem o conceito. O Oracle 21c adicionou armazenamento JSON binário nativo. O Oracle 23ai e 26ai introduziram tipos de dados vetoriais e JSON Relational Duality Views. O navegador de schemas reflete o que o servidor conectado realmente tem — não um superconjunto genérico do 23ai que confunde o desenvolvedor num banco 11g.

Contexto da IA. A camada de IA da Veesker inclui a versão detectada do servidor em cada contexto de prompt enviado ao modelo. Se o banco é 11g, a IA não vai sugerir FETCH FIRST N ROWS ONLY (sintaxe do 12c) nem funções JSON que não existiam em 2011. Se o banco é 23ai, ela oferecerá padrões de busca vetorial com VECTOR_DISTANCE e definições de colunas de embeddings. O modelo é fundamentado no que o servidor realmente é, não no que o Oracle representa no pico do marketing.

Casos extremos que travam outras ferramentas

Resolução de nomes TNS sem Oracle Home. O comportamento padrão do client resolve o tnsnames.ora a partir de $ORACLE_HOME/network/admin. Quando não há Oracle Home — o que é o caso comum quando o Instant Client está empacotado ou instalado via ZIP — a resolução falha silenciosamente e o erro parece um problema de rede. A Veesker resolve o tnsnames.ora a partir de um diretório configurável pelo usuário (o mesmo onde você coloca uma wallet). Strings EZConnect no formato host:porta/service_name funcionam sem nenhum arquivo TNS e são o padrão para novos perfis de conexão.

Conexões com wallet e mTLS. Muitos ambientes Oracle corporativos — e todas as conexões para infraestrutura Oracle Cloud — exigem uma Oracle wallet (cwallet.sso ou ewallet.p12). A Veesker aceita um diretório de wallet no perfil de conexão e o passa ao OCI via parâmetros SSL relevantes. O caminho da wallet é armazenado no gerenciador de credenciais do sistema operacional — DPAPI no Windows, Keychain no macOS, Secret Service no Linux — junto com a senha. Nada vai para um arquivo de configuração em texto simples.

Conexões SYSDBA e SYSOPER. Roles de sessão administrativas exigem Thick mode; o Thin mode não suporta AS SYSDBA. A Veesker expõe o role de conexão como um menu dropdown: Normal, SYSDBA, SYSOPER, SYSBACKUP, SYSDG. O role é passado ao OCI no momento da conexão. O visual da aba muda para sinalizar que a sessão carrega privilégios elevados — um detalhe pequeno que importa quando você tem oito abas abertas e uma delas pode executar DROP DATABASE.

Assinaturas de pacotes específicas por versão. Alguns pacotes internos do Oracle ganharam novos parâmetros obrigatórios entre versões principais. DBMS_STATS.GATHER_TABLE_STATS não é o mesmo procedimento no 11g e no 19c. A documentação de hover da Veesker para chamadas de pacotes PL/SQL é ciente da versão: a lista de parâmetros exibida corresponde à versão que a conexão reportou, não à página de documentação do Oracle mais recente.

O que isso parece num parque misto

O cenário representativo: um desenvolvedor sênior mantém quatro conexões abertas simultaneamente. Uma réplica somente leitura em 11g para um sistema de relatórios legado. Um banco 19c de produção OLTP. Um sandbox 23ai para um piloto de busca vetorial. Uma instância 26ai Cloud para o próximo alvo de migração.

Na Veesker, essas quatro conexões vivem na mesma janela, cada uma ciente de sua versão, cada uma com o conjunto de funcionalidades e o contexto de IA corretos, sem exigir instalação de driver separado ou uma ferramenta diferente. O binário não muda. O Instant Client empacotado dentro dele cobre todo o espectro. O handshake de versão na conexão faz o resto.

Essa é a definição concreta de “9i a 26ai em um único binário.” Não um item de lista numa grade de funcionalidades, mas uma decisão de arquitetura tomada uma vez — sempre Thick mode, sempre client empacotado, sempre comportamento ciente de versão — para que o desenvolvedor nunca precise tomá-la novamente.

Baixe a Veesker e conecte ao seu parque Oracle de múltiplas versões sem instalar um client separado: veesker.cloud/download.

— Veesker