Como integrar Oracle Database com Node.js?

Preparado para adicionar essa skill valiosa ao seu acervo? Vamos começar.

Pré-requisitos e configuração do ambiente

1. Node.js e NPM instalados: recomendamos usar a versão LTS mais recente (v18+).

2. Conhecimento básico de Node.js e Express: você deve estar confortável criando rotas e entendendo middlewares.

3. Acesso a uma instância Oracle Database: pode ser local (via Docker), Oracle Cloud (Free Tier) ou um servidor da sua empresa.

Estrutura inicial do projeto

mkdir node-oracle-api
cd node-oracle-api
npm init -y
npm install express dotenv oracledb

• express: nosso framework web.

• dotenv: para gerenciar variáveis de ambiente (essencial para segurança).

• oracledb: o driver que fará a mágica acontecer.

Variáveis de ambiente

# .env
DB_USER=seu_usuario
DB_PASSWORD=sua_senha_super_secreta
DB_CONNECT_STRING=localhost:1521/XE
# Exemplo para Oracle Cloud pode envolver wallet_location

Entendendo o driver node-oracledb

Modo Thin (padrão atual)

• Características: 100% JavaScript. Implementa o protocolo de rede do Oracle diretamente.

• Vantagens:
• Instalação extremamente simples (apenas npm install oracledb).
• Não requer bibliotecas externas (como o Oracle Instant Client).
• Facilita o deploy em ambientes containerizados e serverless.

• Limitações: não suporta alguns recursos avançados do Oracle, como Application Continuity ou algumas configurações de autenticação avançada.

Modo Thick

• Características: depende de bibliotecas C (Oracle Instant Client).

• Vantagens:
• Suporte total aos recursos avançados do Oracle Database.

• Desvantagens:
• Setup mais complexo, exigindo a instalação e configuração do Oracle Client no ambiente de execução.

Quando usar cada abordagem?

Primeira conexão com Oracle Database

// testConnection.js
require('dotenv').config();
const oracledb = require('oracledb');

const dbConfig = {
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  connectString: process.env.DB_CONNECT_STRING
};

async function runTest() {
  let connection;

  try {
    console.log('Tentando conectar ao Oracle Database...');

    // Estabelecendo a conexão direta
    connection = await oracledb.getConnection(dbConfig);

    console.log('Conexão estabelecida com sucesso!');

    // Executando uma query simples
    const result = await connection.execute(
      `SELECT 'Hello from Oracle, ' || TO_CHAR(SYSDATE, 'DD-MM-YYYY HH24:MI:SS') AS message FROM dual`
    );

    console.log('Resultado da Query:', result.rows[0]);

  } catch (err) {
    console.error('Erro ao conectar ou executar a query:', err.message);
  } finally {
    if (connection) {
      try {
        // Sempre feche a conexão quando terminar de usá-la
        await connection.close();
        console.log('Conexão fechada.');
      } catch (err) {
        console.error('Erro ao fechar a conexão:', err.message);
      }
    }
  }
}

runTest();

🔍 Debug: problemas comuns de conexão

• ORA-12154: verifique seu DB_CONNECT_STRING. O host ou o nome do serviço está incorreto.

• ORA-01017: credenciais incorretas. Verifique DB_USER e DB_PASSWORD.

• ORA-12541: o banco de dados não está rodando ou a porta está bloqueada por um firewall.

Configurando Connection Pooling

Implementação de Pool com node-oracledb

// src/config/database.js
require('dotenv').config();
const oracledb = require('oracledb');

// Configurações recomendadas
oracledb.outFormat = oracledb.OUT_FORMAT_OBJECT; // Retorna resultados como objetos JS

const poolConfig = {
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  connectString: process.env.DB_CONNECT_STRING,
  // Configurações de otimização do pool
  poolMin: 10, // Mínimo de conexões mantidas abertas
  poolMax: 50, // Máximo de conexões permitidas
  poolIncrement: 5, // Quantidade de novas conexões abertas quando necessário
  poolTimeout: 60 // Tempo (segundos) que conexões inativas podem ficar abertas
};

async function initialize() {
  console.log('Inicializando o Connection Pool do Oracle...');
  try {
    await oracledb.createPool(poolConfig);
    console.log('Connection Pool criado com sucesso.');
  } catch (err) {
    console.error('Erro ao inicializar o pool:', err);
    throw err;
  }
}

async function close() {
  console.log('Encerrando o Connection Pool...');
  try {
    // Fecha o pool padrão, dando 10 segundos para conexões em uso terminarem
    await oracledb.getPool().close(10);
    console.log('Connection Pool encerrado.');
  } catch (err) {
    console.error('Erro ao encerrar o pool:', err);
    throw err;
  }
}

// Função auxiliar para executar queries simplificadas
async function simpleExecute(statement, binds = [], opts = {}) {
  let connection;
  let result;

  // Define opções padrão se não forem fornecidas
  opts.autoCommit = opts.autoCommit !== undefined ? opts.autoCommit : true; // Padrão: autoCommit para operações simples

  try {
    // Pega uma conexão do pool
    connection = await oracledb.getConnection();

    // Executa a query
    result = await connection.execute(statement, binds, opts);

  } catch (err) {
    console.error('Erro na execução da query:', err);
    throw err;
  } finally {
    if (connection) {
      try {
        // Libera a conexão de volta para o pool
        await connection.close();
      } catch (err) {
        console.error('Erro ao liberar conexão:', err);
      }
    }
  }

  return result;
}

module.exports = {
  initialize,
  close,
  simpleExecute,
  oracledb // Exportamos o oracledb para acesso a constantes (como BIND_OUT)
};

Gerenciamento do ciclo de vida do Pool

// src/server.js
const express = require('express');
const db = require('./config/database');
const app = express();
const port = process.env.PORT || 3000;

app.use(express.json());

// ... Rotas serão adicionadas aqui ...

async function startup() {
  try {
    await db.initialize(); // Inicializa o pool antes de aceitar conexões
    app.listen(port, () => {
      console.log(`Servidor rodando na porta ${port}`);
    });
  } catch (err) {
    console.error('Falha ao iniciar a aplicação:', err);
    process.exit(1);
  }
}

// Gerenciamento de desligamento 
async function shutdown(e) {
  let err = e;
  console.log('Desligando a aplicação...');
  try {
    await db.close();
  } catch (e) {
    console.error('Erro no desligamento do DB:', e);
    err = err || e;
  }
  process.exit(err ? 1 : 0);
}

process.on('SIGTERM', () => {
  console.log('Recebido SIGTERM');
  shutdown();
});

process.on('SIGINT', () => {
  console.log('Recebido SIGINT (Ctrl+C)');
  shutdown();
});

startup();

📊 Performance: a configuração do pool (poolMin, poolMax) é vital. Monitore o uso do pool em produção para ajustar esses valores. Um pool muito pequeno causa espera; um pool muito grande pode sobrecarregar o banco de dados.

Implementando operações CRUD

Preparando a tabela

CREATE TABLE Funcionarios (
    id NUMBER GENERATED BY DEFAULT ON NULL AS IDENTITY PRIMARY KEY,
    nome VARCHAR2(100) NOT NULL,
    cargo VARCHAR2(50),
    salario NUMBER(10, 2),
    data_admissao DATE DEFAULT SYSDATE
);

Foco na segurança: Bind Variables

// src/models/funcionarioModel.js
const db = require('../config/database');

// READ (Listar e Buscar por ID)
async function find(context) {
  let query = `SELECT id, nome, cargo, salario, data_admissao "dataAdmissao" FROM Funcionarios`;
  const binds = {};

  if (context && context.id) {
    binds.id = context.id;
    query += ` WHERE id = :id`;
  } else {
    query += ` ORDER BY data_admissao DESC`;
  }

  const result = await db.simpleExecute(query, binds);
  return result.rows;
}
module.exports.find = find;

CREATE (inserção de dados)

// src/models/funcionarioModel.js (Continuação)

const createSql = `
INSERT INTO Funcionarios (nome, cargo, salario, data_admissao)
VALUES (:nome, :cargo, :salario, :data_admissao)
RETURNING id INTO :id_out`;

async function create(func) {
  const funcionario = { ...func };

  // Definindo o bind de saída para o ID
  const binds = {
    nome: funcionario.nome,
    cargo: funcionario.cargo,
    salario: funcionario.salario,
    data_admissao: funcionario.data_admissao ? new Date(funcionario.data_admissao) : null,
    id_out: { dir: db.oracledb.BIND_OUT, type: db.oracledb.NUMBER }
  };

  // Passamos { autoCommit: true } como padrão na simpleExecute
  const result = await db.simpleExecute(createSql, binds);

  // Recuperando o ID gerado
  funcionario.id = result.outBinds.id_out[0];
  return funcionario;
}
module.exports.create = create;

⚡ Dica pro: ao trabalhar com datas no Oracle, o node-oracledb converte automaticamente objetos Date do JavaScript para tipos de data/hora do Oracle. Certifique-se de que os dados de entrada sejam convertidos corretamente para Date.

UPDATE e DELETE

// src/models/funcionarioModel.js (Continuação)

// UPDATE
const updateSql = `
UPDATE Funcionarios
SET nome = :nome, cargo = :cargo, salario = :salario
WHERE id = :id`;

async function update(id, func) {
  const funcionario = { ...func, id: id };
  const result = await db.simpleExecute(updateSql, funcionario);

  if (result.rowsAffected && result.rowsAffected === 1) {
    return funcionario;
  } else {
    return null;
  }
}
module.exports.update = update;

// DELETE
const deleteSql = `DELETE FROM Funcionarios WHERE id = :id`;

async function del(id) {
  const binds = { id: id };
  const result = await db.simpleExecute(deleteSql, binds);
  return result.rowsAffected === 1;
}
module.exports.del = del;

Construindo uma API REST completa

Controllers

// src/controllers/funcionarioController.js
const FuncionarioModel = require('../models/funcionarioModel');

// GET /funcionarios e GET /funcionarios/:id
async function get(req, res, next) {
  try {
    const context = {};
    if (req.params.id) {
      context.id = parseInt(req.params.id, 10);
    }

    const rows = await FuncionarioModel.find(context);

    if (context.id) {
      if (rows.length === 1) {
        res.status(200).json(rows[0]);
      } else {
        res.status(404).json({ message: 'Funcionário não encontrado' });
      }
    } else {
      res.status(200).json(rows);
    }
  } catch (err) {
    next(err);
  }
}

// POST /funcionarios
async function post(req, res, next) {
  try {
    // Em um projeto real, valide os dados de entrada aqui (ex: Joi ou Zod)
    const funcionario = {
      nome: req.body.nome,
      cargo: req.body.cargo,
      salario: req.body.salario,
      data_admissao: req.body.data_admissao
    };

    const resultado = await FuncionarioModel.create(funcionario);
    res.status(201).json(resultado);
  } catch (err) {
    next(err);
  }
}

// PUT /funcionarios/:id
async function put(req, res, next) {
  try {
    const id = parseInt(req.params.id, 10);
    const funcionario = {
      nome: req.body.nome,
      cargo: req.body.cargo,
      salario: req.body.salario
    };

    const sucesso = await FuncionarioModel.update(id, funcionario);

    if (sucesso) {
      res.status(200).json(sucesso);
    } else {
      res.status(404).end();
    }
  } catch (err) {
    next(err);
  }
}

// DELETE /funcionarios/:id
async function del(req, res, next) {
  try {
    const id = parseInt(req.params.id, 10);
    const sucesso = await FuncionarioModel.del(id);

    if (sucesso) {
      res.status(204).end(); // No Content
    } else {
      res.status(404).end();
    }
  } catch (err) {
    next(err);
  }
}

module.exports = { get, post, put, del };

Rotas e Integração

// src/routes/funcionarioRoutes.js
const express = require('express');
const router = express.Router();
const funcionarioController = require('../controllers/funcionarioController');

router.get('/:id?', funcionarioController.get);
router.post('/', funcionarioController.post);
router.put('/:id', funcionarioController.put);
router.delete('/:id', funcionarioController.del);

module.exports = router;

// src/server.js (Atualizado)
const express = require('express');
const db = require('./config/database');
const funcionarioRoutes = require('./routes/funcionarioRoutes'); // Importar as rotas
const app = express();
// ... (setup inicial)

app.use(express.json());

// Registrar as rotas da API
app.use('/api/funcionarios', funcionarioRoutes);

// Middleware de tratamento de erros genérico
app.use((err, req, res, next) => {
    console.error(err.stack);
    // Verificar se é um erro do Oracle (ex: violação de constraint)
    if (err.errorNum) {
        res.status(500).json({ message: "Erro no banco de dados", oracleError: err.message, code: err.errorNum });
    } else {
        res.status(500).json({ message: "Erro interno do servidor" });
    }
});

// ... (startup e shutdown permanecem o mesmo)

Gerenciamento de transações

Implementando transações manuais

// Exemplo de função de serviço com transação manual
const oracledb = require('oracledb'); // Usamos o oracledb direto aqui

async function transferenciaBancaria(contaOrigemId, contaDestinoId, valor) {
  let connection;

  try {
    // 1. Obter conexão do pool (sem usar simpleExecute)
    connection = await oracledb.getConnection();

    // Opções para execução sem autoCommit
    const options = { autoCommit: false };

    // 2. Débito na origem
    const sqlDebito = `
      UPDATE Contas SET saldo = saldo - :valor 
      WHERE id = :idOrigem AND saldo >= :valor`;
      
    const resultDebito = await connection.execute(sqlDebito, 
        { valor, idOrigem: contaOrigemId }, options);

    if (resultDebito.rowsAffected === 0) {
        throw new Error('Saldo insuficiente ou conta de origem não encontrada.');
    }

    // 3. Crédito no destino
    const sqlCredito = `
      UPDATE Contas SET saldo = saldo + :valor 
      WHERE id = :idDestino`;
      
    await connection.execute(sqlCredito, 
        { valor, idDestino: contaDestinoId }, options);

    // 4. Commit da Transação
    // Se tudo deu certo até aqui, confirmamos as mudanças
    await connection.commit();
    return { success: true };

  } catch (err) {
    console.error('Erro na transação:', err.message);

    // 5. Rollback da Transação
    if (connection) {
      try {
        await connection.rollback();
      } catch (e) {
        console.error('Erro ao executar rollback:', e);
      }
    }
    throw err; // Propaga o erro original

  } finally {
    // 6. Liberar Conexão (Crucial!)
    if (connection) {
      try {
        await connection.close();
      } catch (err) {
        console.error('Erro ao fechar conexão após transação:', err);
      }
    }
  }
}

Performance e otimização

Tuning de parâmetros do driver (fetch tuning)

1. prefetchRows: quantas linhas o driver deve buscar antecipadamente e armazenar em um buffer interno.

2. fetchArraySize: quantas linhas são retornadas do buffer para a aplicação JavaScript em cada lote.

// Globalmente (no database.js)
oracledb.prefetchRows = 500;
oracledb.fetchArraySize = 500;

// Por consulta
await connection.execute(
  `SELECT * FROM tabela_grande`,
  [],
  { fetchArraySize: 1000 }
);