DEV Community: Danny

Interlúdio Técnico #1 - OracleDB no JavaScript

Danny — Sat, 31 Aug 2024 19:07:25 +0000

Introdução

Oi pessoal! Perdão o sumiço, como falei, ainda estou estabelecendo uma rotina que dá conta de tudo. Pensei muito em criar ou não esse tipo de artigo e decidi ir em frente. Os interlúdios técnicos serão artigos menores focados em soluções, dúvidas, descobertas pontuais que vão surgindo no dia-a-dia, como pequenas pílulas de conhecimento. Na nossa bolha de desenvolvedores temos muitas pessoas excelentes produzindo conteúdo de altíssima qualidade em formatos diferentes: seja no (Atualmente bloqueado) X/Twitter, BlueSky, Threads, aqui no dev.to, no YouTube e outras plataformas. Nesse momento não consigo acompanhar uma produção específica para uma plataforma, então vou escrevendo aqui e repostando nas redes, desculpem o transtorno e peço compreensão. Bora lá.

Para esse primeiro interlúdio, decidi escrever sobre um querido do mundo enterprise, um banco que para javeiros é mais um dia qualquer, mas pode assombrar devs em outras stacks. Hoje vou falar do OracleDB, ou mais especificamente como construir um backend ou função Lambda que utilize OracleDB em JavaScript/TypeScript.

Por que OracleDB?

Não me pergunte, eu era uma criança quando isso ocorreu. O que posso dizer é que em mais de uma firma para qual trabalhei, os sistemas legados utilizam esse banco, e na modernização desses sistemas, seja uma refatoração apenas de código ou também de arquitetura, há alguns impecilhos para uma implementação de um backend JavaScript/TypeScript.

Drivers proprietários e o node-oracledb

Um banco Oracle em produção geralmente utiliza os recursos proprietários do banco para estabalecer conexões e dentre eles está o NNE (Native Network Encryption ou Criptograifa Nativa de Rede). Esse é o vilão da história, pois o node-oracledb traz apenas um cliente básico, ou como denominado pela prórpia Oracle, o thin-mode ou modo-magro na tradução ao pé da letra. Faz sentido o magro nesse contexto pois essa bilbioteca não traz o driver "cheio" da Oracle, que possui suporte ao NNE.

Instalando o driver em um backend TypeScript/JavaScript

Acredito que em um setup bem simples (como um sistema de arquivos ou armazenamento estático para guardar o código e uma instância de computação), os drivers podem ser copiados diretamente com o código fonte ou compilado e o carregamento do driver configurado para o caminho dos binários do driver, porém aqui vou trabalhar com uma solução baseada em Docker, pois vai garantir reprodutibilidade para deploys em Kubernetes, serviços Cloud baseados em Kubernetes, serviços cloud baseados em imagem Docker e instância de computação e serviços Cloud serverless que suportam imagens Docker.

Para manuais, mais informações e documentação oficial, vou disponibilizar uma lista abaixo com os links mais úteis:

Observações

O nome oficial do driver "cheio" (thick-mode) da Oracle é Instant Client.
Embora sejam disponiblizadas opções Docker com o Client pré-instalado, você pode encontrar problemas caso utilize uma Dockerfile multi-estágios, isso porque o Oracle Linux trabalha com binários compilados com MUSL, enquanto outras distribuições (inclusive as mais utilizadas para rodar o código final) utilizam GLIBC. Novamente, para fins de reprodutibilidade, demonstrarei aqui o caminho que em diferentes firmas foi a solução adotada, que consiste em baixar o Instant Client e copiá-lo para um diretório dentro da imagem Docker.

Dockerizando a aplicação

Vamos iniciar com o caso mais simples: você possui a liberdade para utilizar o Oracle Linux. Vamos assumir um ponto de entrada index.js.

FROM oraclelinux:8

RUN  dnf -y install oracle-instantclient-release-el8 && \
    dnf -y install oracle-instantclient-basic oracle-instantclient-devel oracle-instantclient-sqlplus && \
    rm -rf /var/cache/dnf

RUN dnf -y module enable nodejs:18 && \
    dnf -y install nodejs npm && \
    rm -rf /var/cache/dnf

WORKDIR /app

COPY . .

RUN npm install
RUN npm run build

ARG PORT=3000
EXPOSE $PORT

CMD [ "npm", "run", "start" ]

// index.js
import { initOracleClient } from 'oracledb'

initOracleClient();

Como a imagem já possui os caminhos (paths) todos preparados, esse setup já é suficiente para inicializar o driver.

Agora, assumindo que não seja possível utilizar a imagem oraclelinux, o mesmo resultado pode ser atingido com um estágio para baixar o Instant Client:

# Neste estágio são instaladas as dependências do projeto
FROM node:18-alpine AS deps
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

# Neste, o projeto é compilado. A separação desse estágio da
# instalação das dependências presume um processo de empacotamento
# (bundling) do código com as dependências necessárias, de forma a
# evitar uma pasta node_modules na imagem final
FROM node:18-alpine AS builder
WORKDIR /app

COPY . .
COPY --from=deps /app/node_modules ./node_modules

RUN npm run build

FROM node:18-alpine as download
WORKDIR /app

# São instalados os pacotes necessários para baixar e extrair
# os binários
RUN apk add --no-cache wget unzip
# A escolha de versão aqui (não é a última) se dá pela versão do
# GLIBC utilizada
RUN wget --no-cookies https://download.oracle.com/otn_software/linux/instantclient/2115000/instantclient-basic-linux.x64-21.15.0.0.0dbru.zip
# Aqui é criado o diretório para expandir o arquivo .zip e é
# executada a extração
RUN mkdir -p instantclient
RUN unzip instantclient-basic-linux.x64-21.15.0.0.0dbru.zip -d instantclient
# Por final, o arquivo .zip é apagado
RUN rm instantclient-basic-linux.x64-21.15.0.0.0dbru.zip
# Todos os comandos aqui devem ser concatenadaos utilizando '&&'
# e quebra de linha (\), optei pela verbosidade para comentar a
# solução linha por linha

FROM node:18-alpine as runner

# Aqui são configurados os caminhos de ambiente para o driver
ENV PORT=3000 PATH=$PATH:$ORACLE_HOME LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/oracle/instantclient_21_15
WORKDIR /app
RUN apk add --no-cache libc6-compat

# Finalmente, o código compilado e empacotado é copiado para o
# estágio final, bem como o Instant Client.
# A escolha do diretório /opt se dá por uma convenção, pois é
# o mesmo diretório utilizado am ambientes AWS Lambda para
# carregar camadas e arquivos complementares
COPY --from=builder /app/<seu diretório de output da build> ./
# Como não existirá uma pasta node_modules no estágio final, são
# copiados os binários do node-oracledb também
COPY --from=builder /app/node_modules/oracledb/build /opt/build
COPY --from=download /app/instantclient_21_15 /opt/oracle/instantclient_21_15

CMD ["npm", "run", "start"]

// index.js
import { initOracleClient } from 'oracledb'

initOracleClient({ binaryDir: '/opt/build/Release', libDir: '/opt/oracle/instantclient_21_15' });

Conclusão

A partir desse setup mínimo, seu serviço ou API está preparado para utilizar um banco Oracle com NNE, lembrando que o driver deve ser inicalizado antes de tentar se conectar ou formar uma piscina (pool) de conexões para utilizar o banco. Não desenvolvi uma solução de exemplo para este artigo pela diversidade de aplicações possíveis e suas bibliotecas e frameworks desenhados para cada tipo de solução, pessoalmente já desenvolvi tanto APIs REST quanto serviços engatilhados por eventos utilizando configurações parecidas.
Nada nesse artigo é original: tudo pode ser encontrado em perguntas e respostas no StackOverflow, pode ser desenvolvido a partir de um rascunho de prompts de um ChatGPT ou Claude, minha missão aqui é produzir um ponto de partida em Português e condensar a experiência.

Novamente, agradeço a leitura e a atenção! Até breve.

Generator Functions, um caso de uso

Danny — Tue, 06 Aug 2024 17:41:40 +0000

Contexto

Oi! Antes de iniciar propriamente esse artigo, gostaria de apresentar o contexto de como cheguei a utilizar uma generator function para resolver um problema.

Tudo começa alguns anos atrás quando pensei no meu projeto final do bootcamp que participei. A ideia inicial era um portal que agregava dados sobre políticos como notícias, projetos, votações e etc. Isso evoluiu para uma plataforma que utiliza os bancos eleitorais do TSE para monitorar políticos que estão exercendo cargos eletivos diretos. Esses bancos do TSE são distribuídos em formato CSV, mas não são perfeitos. Só nesses anos tentando evoluir esse projeto, os bancos melhoraram muito, e no meio do caminho o Brasil API veio ao mundo também e me inspirou ainda mais.

Mesmo que a stack do projeto já estivesse definida, estar constantemente atualizando meu banco principal com as constantes atualizações dos CSVs, corrigindo inconsistências e o tempo para se importar tudo se tornaram grandes empecilhos e percebi que precisaria de um programa só para lidar com isso. Começa a aventura da CLI que montei para resolver esse problema.

Inicialmente, a ideia era simples: ler o CSV, lotear os dados e salvar os lotes no banco. Fui testando o tempo médio que levava para salvar tanto um a um, quanto vários de uma vez e qual tamanho de lote tinha o melhor tempo médio, mas nada muito criterioso ou exato (inclusive se alguém testar ou souber otimizações do tipo para MongoDB, aceito a crítica/sugestão). E funcionava legal, tinha agora um jeito rápido de passar o caminho do CSV para uma CLI que resolvia o meu problema.

Já nem pensava mais nessa CLI, até que em uma viagem queria codar nesse projeto, meu notebook não tinha o banco e só 8GB de RAM, ou seja, era um editor de código e um sonho. Obviamente ele me deixou na mão porque o código era bem básico e subia todo o arquivo na memória antes de salvar no banco. Nessa altura, já havia lido sobre funções que "retornavam mais de uma vez" e a palavra reservada yield, pensei que era uma oportunidade interessante, fazia sentido pois a biblioteca de leitura de CSV que utilizei na CLI já possuia uma API para processar o CSV linha por linha.

O problema

Com apenas 8GB de RAM, o desafio de otimização era refatorar a CLI para processar o arquivo linha por linha, em vez de carregar tudo na memória. Até então o fluxo era bem simples: carregar arquivo na memória, lotear e salvar os lotes no banco. Como repensar esse fluxo?

Pensando a solução

O primeiro passo foi decidir o que manter. Bom, toda a estrutura da CLI vai ficar igual, o tamanho do lote vai ficar igual, operações de banco, vou mexer apenas na função que faz a leitura e como as operações de banco vão ocorrer quando mexer nessa parte. O segundo passo foi juntar curiosidade com aplicabilidade: como usar uma generator function para implementar a solução?

Isso levou a uma série de considerações para escrever a solução:

O ideal é manter o loteamento de inserts no banco para garantir a performance dessa etapa, mas é necessário evitar a qualquer custo carregar mais dados na memória do que o essencial, então cada lote precisa ser preparado já no processamento do CSV
Será necessário pensar bem onde bloquear e não bloquear o loop de eventos para garantir que nada está se perdendo ou lotes incompletos sejam processados sem comprometer a eficiência de memória e velocidade
Será necessário usar async para juntar cada lote antes de entregar para o banco de dados salvar (para minha surpresa, existem Async Generators também!)
Cada lote que estiver pronto precisa ser entregue para o banco salvar

A cada consideração, ficou mais claro que uma Generator Function era exatamente o que eu precisava.

Detalhe

Pensar a solução não foi um processo muito custoso pois implementei na CLI uma estrutura parecida com as camadas de uma API convencional. Os comandos são como controllers e os serviços definem e executam o contrato. Em uma API existem mais camadas, mas como é uma CLI optei por não abstrair as operações de banco e usar a pasta /lib para organizar funcionalidades que são utilizadas nos serviços. É nesses momentos que o seu eu de agora agradece o seu eu do passado pelo código organizado que permite alterações de todos os tamanhos com pouco esforço ou retrabalho.

Implementando a solução

O primeiro passo aqui foi entender como e quais recursos de Async Generators vou utilizar. Os exemplos disponíveis na MDN já foram de grande ajuda para elaborar uma solução:

Particularmente o último link foi muito útil para pensar como estaria chamando essa função para salvar os dados no banco, utilizando um loop for...of assíncrono. Como essa parte da solução já era óbvia, implementei.

const promises = [];
  try {
    await mongoConnect(mongoUri);
    for await (const batch of parse(pathUri)) {
      promises.push(TseCandidate.insertMany(batch)
        .then(() => console.log(`${log.success}Batch entries imported with success`))
        .catch((err: any) => {
          console.log(log.error, err);
          throw new AppError({
            message: err.message || 'Error importing batch entries',
            method: 'parseAndImportDb',
            field: JSON.stringify(batch, null, 2)
          })
        })
      );
    }
    await Promise.all(promises);
    await mongoDisconnect();
  } catch (error) {
    throw error;
  }

Uma coisa já estava garantida portanto: cada lote de arquivos que ficar pronto é resolvido e imediatamente enviado para o banco. O resto do código serve basicamente para reportar no terminal o progresso ou eventuais erros das operações e garantir controle de fluxo.

Utilizando o .then/.catch da promessa do banco, garanto que cada lote que for salvo com sucesso é independentemente reportado no terminal
Utilizando o Promise.all, garanto que todas as operações de banco terminem antes de encerrar a conexão.

É importante notar que o Promise.all joga um erro se qualquer uma das promessas falhar, então qualquer problema salvando um lote no banco compromete todo o resto da operação. Mas esse comportamento é desejado: preciso entender a razão do erro e corrigir o código ou entender uma inconsistência/corrupção de dados que possa estar ocorrendo e resolver isso. Como um banco incompleto é inútil e precisarei apagar tudo e começar novamente, não faz sentido correr o processo até o final, mas é importante conhecer o Promise.allSettled também!

Implementando o Async Generator

Até então, a implementação era baseada em "embalar" a API da bilbioteca de leitura de CSV em uma promessa:

new Promise((resolve, reject) => {
  Papa.parse<ICandidate>(fs.createReadStream(url), {
    encoding: 'latin1',
    header: true,
    skipEmptyLines: true,
    complete: (results: IParseResult) => {
      console.log(`${log.info}${String(results.data.length).green} entries parsed`);
      const resultsErrorsLength = results.errors.length;
      console.log(`${
        resultsErrorsLength < 1
          ? log.success + String(resultsErrorsLength).green
          : log.error + String(results.errors.length).red
      } parsing errors`);
      if (results.errors.length > 0) {
        reject(new AppError({
          message: 'Errors were found on the table, import cancelled'.red,
          method: 'parse',
          module: 'ParserLib',
          step: 'Complete',
          field: JSON.stringify(results.errors).gray,
          })
        );
      }
      resolve(results.data);
    },
    error: (err) =>
      reject(new AppError({
        message: err.message.red,
        method: 'Parse',
        module: 'ParserLib',
      })),
    })
});

Essa implementação utilizava apenas a callback complete da biblioteca, a ideia agora é utilizar a step. Para quem estiver mais curioso sobre a biblioteca, chama-se Papaparse.

Vamos enfim ao esboço dessa refatoração:

// Note o asterisco caracterizando a função como um gerador assíncrono
export async function* parse(url: string): AsyncGenerator<ICandidate[]> {
  // Temos aqui nosso tamanho de lote e array que acumulará as linhas em um lote
  const batchSize = 5000;
  let batch: ICandidate[] = [];

  // Temos aqui duas lets com uma promise e um resolver.
  // Note que a promise recebe o resolver externo como resolver
  // dela.
  let resolve: (value: ICandidate[]) => void;
  let promise = new Promise<ICandidate[]>(r => resolve = r);

  Papa.parse<ICandidate>(createReadStream(url), {
    // Utilizei latin1 pois é a codificação dos bancos do TSE
    encoding: 'latin1',
    header: true,
    skipEmptyLines: true,
    delimiter: ';',
    step: (results) => {
      // nossa lógica 'linha por linha' vai aqui
    },
    complete: (results) => {
      // Nossa lógica para finalizar o processamento vai aqui
    }
  });

  // Aqui fica tudo mais interessante: utilizando de um
  // 'loop infinito', vamos travar o loop para aguardar a
  // promessa e se ele for um array (ou seja, um lote de dados)
  // rendemos ele ao loop do serviço para inserir no banco
  while (true) {
    const result = await promise;
    if (result instanceof Array) yield result;
  }
}

Fora a lógica principal de processamento, ainda é preciso lidar com a condição de parada do loop.

É importante ressaltar como o fluxo dessa solução está estruturado: para cada lote de dados acumuluado, a ideia é utilizar o resolver para resolver a promessa, "entregando" o lote de dados para o loop, que vai render (yield) para outro loop. A utilização de lets tem uma dupla função:

permitir a redesignação do lote e da promessa, garantindo que o array está vazio e o loop está aguardando a promessa resolver ou rejeitar
dereferenciar o lote e a promessa antigos. Ao eliminar todas as referências ativas de um objeto, ele pode ser marcado para coleta de lixo, e ao usar redesignação, isso é realizado intencionalmente.

Um pouco mais a fundo - Coleta de lixo

Vou deixar a introdução desse tópico para um bom artigo que encontrei sobre coleta de lixo no Node:

Node.js Por Baixo dos Panos #9: Coletando o Lixo

Lucas Santos ・ Apr 6 '20

#node #javascript #v8 #computerscience

Um aspecto importante para se notar é que ao dereferenciar constantemente os dados/promessa antigos, poucas ou até nenhuma referência sobrevive a um ciclo de coleta no espaço novo, a memória é liberada o quanto antes.

Processando as linhas

Cada linha processada dispara a callback definida em step. Basta então acessar o dado e acumular no lote. Por fim, quando o lote possuir o tamanho desejado, a promessa é resolvida com o lote e tanto o array quanto a promessa são redesignados.

step: (results) => {
  batch.push(results.data);
  if (batch.length >= batchSize) {
    resolve(batch);
    batch = [];
    promise = new Promise(r => resolve = r);
  }
},

Processando o último lote e criando o sinal de parada

Agora a callback de complete apenas resolve o último lote de linhas. Para a condição de parada, é criada mais uma promise que resolve com o objeto { done: true }. Isso será avaliado no loop da função para encerrar.

complete: (results) => {
  if (batch.length > 0) {
    console.log(log.success + 'Last batch parsed with success!');
    resolve(batch);
    batch = [];
    promise = new Promise(r => resolve = r);
  };
  resolve({ done: true });
}

Parando o loop

Para finalizar a implementação, basta validar no loop se há o sinal de parada e retornar. A implementação completa ficou assim:

export async function* parse(url: string): AsyncGenerator<ICandidate[]> {
  const batchSize = 5000;
  let batch: ICandidate[] = [];

  let resolve: (value: ICandidate[] | { done: boolean }) => void;
  let promise = new Promise<ICandidate[] | { done: boolean }>(r => resolve = r);
  Papa.parse<ICandidate>(createReadStream(url), {
    encoding: 'latin1',
    header: true,
    skipEmptyLines: true,
    delimiter: ';',
    step: (results) => {
      batch.push(results.data);
      if (batch.length >= batchSize) {
        resolve(batch);
        batch = [];
        promise = new Promise(r => resolve = r);
      }
    },
    complete: (results) => {
      if (batch.length > 0) {
        console.log(log.success + 'Last batch parsed with success!');
        resolve(batch);
        batch = [];
        promise = new Promise(r => resolve = r);
      };
      resolve({ done: true });
    }
  });

  while (true) {
    const result = await promise;
    if (result instanceof Array) yield result;
    if (!(result instanceof Array) && result.done) return;
  }
}

Considerações finais

Essa não é a solução que melhor utiliza os recursos de async generators, mas foi a solução que resolveu meu problema. Com ela, todo o processamento de dados foi otimizado e um trabalho que exigia um montante cada vez maior de memória agora exige um montante quase constante, permitindo até um sofrido notebook de 8GB de RAM montar um banco com milhares ou até milhões de linhas, em questão de minutos.

Para complementar a funcionalidade e facilitar ainda mais, incluí um comando de Download na CLI, automatizando o trabalho de acessar e baixar os CSVs atualizados. Mas falta muita coisa. Ainda faltam funcionalidades de normalização de dados, descompactar seletivamente um CSV do arquivo fonte, um modo interativo e futuramente suporte a bancos relacionais.

O repositório está público, aberto a contribuições (embora a CLI ainda não esteja publicada, ainda falte um Código de Conduta e Regras de Contribuição) e possui uma licença CC BY-NC-ND 4.0 pois acredito firmemente que o trabalhar com dados públicos exige zelo com a análise que se pretende realizar e com o público que venha a consumir esses dados, portanto, essa licensa impede derivativos diretos da CLI, para evitar que a ferramenta seja utilizada para (por exemplo) difundir desinformação ou análises enviezadas. A ideia é construir uma ferramenta de qualidade para uso geral.

Peço perdão em adianto pela bagunça no código do repositório, nos momentos de luta implementei um logger da idade das pedras para persistir tudo em um arquivo de texto/JSON, mas é mais um dos itens que será bem trabalhado a seguir. Essa CLI ainda está meio longe de ser lançada.

Conclusão

Espero que esse artigo não seja tão maçante para o leitor e que ajude a esclarecer alguns recursos da língua ou ao menos sirva de inspiração para aventuras semelhantes de otimização. É minha primeira vez escrevendo um artigo do tipo, pretendo escrever outros e com cada vez mais qualidade.

Muito obrigado pelo seu tempo e espero que tenha curtido. Até a próxima!

Olá mundo!

Danny — Mon, 15 Jul 2024 02:16:26 +0000

Criei este perfil para compartilhar o que ando estudando, os projetos que estou desenvolvendo e as aventuras técnicas que resultam deles. Espero que os conteúdos que eu poste aqui sejam úteis ou ao menos informativos para quem os ler, e de repente ajude com algum problema similar que esteja enfrentando. Tentarei ser o mais acessível possível, é minha intenção fazer parte dessa rede/bolha de desenvolvedores brasileiros que se esforçam para produzir um conteúdo muito bom e que diversas vezes já me ajudou a aprender e resolver problemas, tanto em projetos pessoais quanto em produtos profissionais das firmas onde já trabalhei.

Os posts serão escritos em pt-BR e pretendo abordar assuntos mais relacionados a projetos que estou construindo. Dessa forma, não vou produzir posts sobre assuntos mais básicos ou iniciantes das stacks/langs que uso ou vou usar, ao menos não inicialmente.

Espero conseguir manter uma frequência semanal de posts, mas não sou de ferro e trabalho muito na semana. De qualquer maneira, uma calorosa recepção da pessoinha aqui do outro lado da tela!