—

Oracle Database Node for n8n

Advanced Oracle Database node for n8n with enterprise features for heavy workloads and complete support for Oracle 19c+ and Oracle 23ai.

> Version 1.1.6 — Official n8n build system (@n8n/node-cli), full thin/thick mode support per credential.

—

About

A complete enterprise solution for Oracle Database in the n8n ecosystem, built with node-oracledb 6.x and supporting both connection modes — Thin (pure JS, zero Oracle Client required) and Thick (Oracle Client libraries, full feature set).

Developed by: Jônatas Meireles Sousa Vieira
Based on: n8n-nodes-oracle-database by Matheus Peluchi

—

Project Structure

n8n-nodes-oracle-database/
├── credentials/
│   └── Oracle.credentials.ts           # Oracle credentials (thin/thick)
├── nodes/
│   └── Oracle/
│       ├── OracleDatabase.node.ts          # Basic node — SQL with bind variables
│       ├── OracleDatabaseAdvanced.node.ts  # Advanced node — PL/SQL, bulk, AQ
│       ├── OracleVectorStore.node.ts       # Vector store — Oracle 23ai
│       ├── ChatMemory.node.ts              # Chat history — session management
│       ├── oracle.svg
│       └── core/
│           ├── connection.ts           # Connection manager (thin/thick)
│           ├── connectionPool.ts       # Connection pooling
│           ├── bulkOperations.ts       # Bulk Insert/Update/Delete/Upsert
│           ├── plsqlExecutor.ts        # PL/SQL anonymous blocks, procedures, functions
│           ├── transactionManager.ts   # Transactions with savepoints
│           ├── aqOperations.ts         # Oracle Advanced Queuing
│           ├── interfaces/
│           │   └── database.interface.ts
│           ├── types/
│           │   └── oracle.credentials.type.ts
│           └── utils/
│               └── error-handler.ts
└── dist/                               # Compiled build (auto-generated)

—

Features

Connection Modes

| Mode | Oracle Client | Best for |
|——|—————|———|
| Thin (default) | Not required — pure JavaScript driver | Containers, cloud, quick setup |
| Thick | Required — Oracle Instant Client | Wallets, Kerberos, LDAP, maximum performance |

> The mode is set per credential — each credential can use a different mode independently.

Available Nodes

#### Oracle Database (Basic)
Simple SQL execution with parameterized queries and IN-list parsing.

• SQL queries with named bind variables (:param)
• Support for String, Number data types
• Parse values for IN statements (comma-separated → individual binds)

#### Oracle Database Advanced
Enterprise operations with connection pool selection.

| Operation | Description |
|———–|————-|
| SQL Query | Parameterized queries with String, Number, Date, CLOB, OUT types |
| PL/SQL Block | Anonymous blocks with automatic OUT parameter detection |
| Stored Procedure | BEGIN proc(:p1, :p2); END; via PL/SQL executor |
| Function | BEGIN :result := func(:p1); END; via PL/SQL executor |
| Bulk Operations | Mass Insert with configurable batch size and error control |
| Transaction Block | Multi-statement transactions with per-operation savepoints |
| Oracle AQ | Advanced Queuing — queue info and monitoring |

Connection pool presets: Standard, High Volume, OLTP, Analytics, or Single Connection.

#### Oracle Vector Store
Vector store management for Oracle 23ai with native VECTOR type support.

| Operation | Description |
|———–|————-|
| Setup Collection | Create table + HNSW vector index with configurable dimension |
| Add Document | Insert document with embedding (float32 array) |
| Search Similarity | Nearest-neighbor search (Cosine, Euclidean, Dot Product) |
| Get / Update / Delete Document | Document CRUD by ID |
| List Collections | List vector store tables |

#### Oracle Chat Memory
Session-based chat history stored in Oracle.

| Operation | Description |
|———–|————-|
| Setup Table | Create session table + session index |
| Add Message | Store user / assistant / system message |
| Get Messages | Retrieve full session history ordered by timestamp |
| Clear Memory | Delete all messages for a session |
| Get Summary | Message count by type, first/last timestamps |

—

Installation

Thin Mode (no Oracle Client)

npm install @jonales/n8n-nodes-oracle-database

Works immediately in any Node.js environment — containers, cloud, local.

Thick Mode (Oracle Instant Client required)

Install Oracle Instant Client first, then install the package.

Linux / macOS:

Download and extract Oracle Instant Client
wget https://download.oracle.com/otn_software/linux/instantclient/2340000/instantclient-basic-linux.x64-23.4.0.24.05.zip
unzip instantclient-basic-linux.x64-23.4.0.24.05.zip -d /opt/oracle/
export LDLIBRARYPATH=/opt/oracle/instantclient234:$LDLIBRARYPATH
npm install @jonales/n8n-nodes-oracle-database

Windows:

Extract Oracle Instant Client to C:oracleinstantclient234
Add to system PATH:
$env:PATH += ";C:oracleinstantclient234"
npm install @jonales/n8n-nodes-oracle-database

Docker (thick mode):

FROM n8nio/n8n:latest
RUN apt-get update && apt-get install -y wget unzip libaio1
RUN wget https://download.oracle.com/otn_software/linux/instantclient/2340000/instantclient-basic-linux.x64-23.4.0.24.05.zip
RUN unzip instantclient-basic-linux.x64-23.4.0.24.05.zip -d /opt/oracle/
ENV LDLIBRARYPATH=/opt/oracle/instantclient234
RUN npm install @jonales/n8n-nodes-oracle-database

—

Credentials Configuration

| Field | Description | Example |
|——-|————-|———|
| User | Oracle database user | hr or system |
| Password | User password | your_password |
| Connection String | Host:port/service or TNS alias | localhost:1521/XEPDB1 |
| Connection Mode | Thin (default) or Thick | Thin Mode |
| Oracle Client Directory | Thick mode only — path to Instant Client | /opt/oracle/instantclient234 |
| Oracle Config Directory | Thick mode only — tnsnames.ora location | /opt/oracle/network/admin |

Connection string examples:

Oracle XE (local)
localhost:1521/XEPDB1
Oracle Enterprise
oracle-server.company.com:1521/PROD
Oracle Autonomous (OCI)
adb.us-ashburn-1.oraclecloud.com:1522/service_high.adb.oraclecloud.com
Oracle RDS (AWS)
mydb.cluster-xyz.us-east-1.rds.amazonaws.com:1521/ORCL
TNS alias (thick mode with tnsnames.ora)
MYTNSALIAS

—

Thin vs Thick Mode — When to Use Each

Thin Mode

• No installation required
• Works in Docker, Kubernetes, cloud functions
• Supports most Oracle features (SQL, PL/SQL, bind variables, LOBs)
• Default for all four nodes

Thick Mode

Use Thick when you need:

• Oracle Wallets (mTLS / Autonomous Database without connection string)
• Kerberos or LDAP authentication
• Oracle Net Services (advanced network config)
• Some older Oracle-specific features (pre-12c compatibility)

> Important: Oracle initializes the driver mode once per process. If the first connection in the n8n process is Thin, all subsequent connections in that process will also be Thin. To guarantee Thick mode, set all credentials to Thick Mode, or restart n8n after changing the mode.

—

Troubleshooting

Thin mode — connection refused

• Check connection string format: host:1521/service_name
• Verify firewall is not blocking port 1521 (or your Oracle port)
• Test network: telnet hostname 1521

Thick mode — DPI-1047 (Oracle Client not found)

• Verify Oracle Instant Client is installed
• Set LDLIBRARYPATH (Linux/macOS) or add to PATH (Windows) pointing to the client directory
• Or set the Oracle Client Directory field in credentials
• Oracle Client version must be compatible with your database version

Thick mode — DPI-1072 (already initialized)

• This is informational — the driver was already initialized in a previous call. No action needed.

—

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm run lint         # ESLint check
npm run lint:fix     # ESLint auto-fix

—

Contributing

1. Fork the repository
2. Create a feature branch
3. Implement changes and run npm run build
4. Open a Pull Request

—

Support the Project

PIX



PIX Key: jonatas.mei@outlook.com

Cryptocurrency

Bitcoin (BTC) bc1qdq9rj7565c4fvr7t3xut6z0tjd65p4mudrc0ll Pay with Trust Wallet	Ethereum (ETH) 0xA35A984401Ae9c81ca2d742977E603421df45419 Pay with Trust Wallet
Binance (BNB) 0xA35A984401Ae9c81ca2d742977E603421df45419 Pay with Trust Wallet	Polygon (POL) 0xA35A984401Ae9c81ca2d742977E603421df45419 Pay with Trust Wallet

—

License

MIT — see LICENSE.md

—

Author

Jônatas Meireles Sousa Vieira
Email: jonatas.mei@outlook.com
GitHub: @jonales
LinkedIn: jonatasmeireles

—

If this project was useful, consider giving it a star!


Made with ❤️ for Oracle & n8n communities

—

Node Oracle Database para n8n

Node avançado Oracle Database para n8n com recursos empresariais para cargas pesadas e suporte completo ao Oracle 19c+ e Oracle 23ai.

> Versão 1.1.6 — Build oficial n8n (@n8n/node-cli), suporte completo thin/thick mode por credencial.

—

Sobre

Solução empresarial completa para Oracle Database no ecossistema n8n, construída com node-oracledb 6.x e com suporte a ambos os modos de conexão — Thin (JavaScript puro, sem Oracle Client) e Thick (Oracle Client libraries, conjunto completo de funcionalidades).

Desenvolvido por: Jônatas Meireles Sousa Vieira
Baseado em: n8n-nodes-oracle-database por Matheus Peluchi

—

Estrutura do Projeto

n8n-nodes-oracle-database/
├── credentials/
│   └── Oracle.credentials.ts           # Credenciais Oracle (thin/thick)
├── nodes/
│   └── Oracle/
│       ├── OracleDatabase.node.ts          # Node básico — SQL com bind variables
│       ├── OracleDatabaseAdvanced.node.ts  # Node avançado — PL/SQL, bulk, AQ
│       ├── OracleVectorStore.node.ts       # Vector store — Oracle 23ai
│       ├── ChatMemory.node.ts              # Histórico de chat — sessões
│       ├── oracle.svg
│       └── core/
│           ├── connection.ts           # Gerenciador de conexão (thin/thick)
│           ├── connectionPool.ts       # Pool de conexões
│           ├── bulkOperations.ts       # Bulk Insert/Update/Delete/Upsert
│           ├── plsqlExecutor.ts        # PL/SQL: blocos, procedures, functions
│           ├── transactionManager.ts   # Transações com savepoints
│           ├── aqOperations.ts         # Oracle Advanced Queuing
│           ├── interfaces/
│           │   └── database.interface.ts
│           ├── types/
│           │   └── oracle.credentials.type.ts
│           └── utils/
│               └── error-handler.ts
└── dist/                               # Build compilado (auto-gerado)

—

Funcionalidades

Modos de Conexão

| Modo | Oracle Client | Indicado para |
|——|—————|—————|
| Thin (padrão) | Não necessário — driver JavaScript puro | Containers, cloud, setup rápido |
| Thick | Necessário — Oracle Instant Client | Wallets, Kerberos, LDAP, máxima performance |

> O modo é configurado por credencial — cada credencial pode usar um modo diferente de forma independente.

Nodes Disponíveis

#### Oracle Database (Básico)
Execução SQL com queries parametrizadas e suporte a listas IN.

#### Oracle Database Advanced
Operações empresariais com seleção de pool de conexão.

| Operação | Descrição |
|———-|———–|
| SQL Query | Queries parametrizadas com tipos String, Number, Date, CLOB, OUT |
| PL/SQL Block | Blocos anônimos com detecção automática de parâmetros OUT |
| Stored Procedure | BEGIN proc(:p1, :p2); END; via executor PL/SQL |
| Function | BEGIN :result := func(:p1); END; via executor PL/SQL |
| Bulk Operations | Insert em massa com batch size configurável e controle de erros |
| Transaction Block | Transações multi-statement com savepoint por operação |
| Oracle AQ | Advanced Queuing — informações de fila e monitoramento |

Pools disponíveis: Standard, High Volume, OLTP, Analytics ou Single Connection.

#### Oracle Vector Store
Gerenciamento de vector store para Oracle 23ai com suporte nativo ao tipo VECTOR.

| Operação | Descrição |
|———-|———–|
| Setup Collection | Cria tabela + índice vetorial HNSW com dimensão configurável |
| Add Document | Insere documento com embedding (array float32) |
| Search Similarity | Busca por vizinhança (Cosine, Euclidean, Dot Product) |
| Get / Update / Delete Document | CRUD de documento por ID |
| List Collections | Lista tabelas de vector store |

#### Oracle Chat Memory
Histórico de chat por sessão armazenado no Oracle.

| Operação | Descrição |
|———-|———–|
| Setup Table | Cria tabela de sessão + índice |
| Add Message | Salva mensagem user / assistant / system |
| Get Messages | Recupera histórico completo ordenado por timestamp |
| Clear Memory | Remove todas as mensagens de uma sessão |
| Get Summary | Contagem por tipo, primeiro e último timestamp |

—

Instalação

Thin Mode (sem Oracle Client)

npm install @jonales/n8n-nodes-oracle-database

Funciona imediatamente em qualquer ambiente Node.js — containers, cloud, local.

Thick Mode (Oracle Instant Client obrigatório)

Instale o Oracle Instant Client primeiro, depois o pacote.

Linux / macOS:

wget https://download.oracle.com/otn_software/linux/instantclient/2340000/instantclient-basic-linux.x64-23.4.0.24.05.zip
unzip instantclient-basic-linux.x64-23.4.0.24.05.zip -d /opt/oracle/
export LDLIBRARYPATH=/opt/oracle/instantclient234:$LDLIBRARYPATH
npm install @jonales/n8n-nodes-oracle-database

Windows:

Extraia o Oracle Instant Client em C:oracleinstantclient234
Adicione ao PATH do sistema:
$env:PATH += ";C:oracleinstantclient234"
npm install @jonales/n8n-nodes-oracle-database

Docker (thick mode):

FROM n8nio/n8n:latest
RUN apt-get update && apt-get install -y wget unzip libaio1
RUN wget https://download.oracle.com/otn_software/linux/instantclient/2340000/instantclient-basic-linux.x64-23.4.0.24.05.zip
RUN unzip instantclient-basic-linux.x64-23.4.0.24.05.zip -d /opt/oracle/
ENV LDLIBRARYPATH=/opt/oracle/instantclient234
RUN npm install @jonales/n8n-nodes-oracle-database

—

Configuração de Credenciais

| Campo | Descrição | Exemplo |
|——-|———–|———|
| User | Usuário Oracle | hr ou system |
| Password | Senha do usuário | sua_senha |
| Connection String | Host:porta/serviço ou TNS alias | localhost:1521/XEPDB1 |
| Connection Mode | Thin (padrão) ou Thick | Thin Mode |
| Oracle Client Directory | Apenas thick — caminho do Instant Client | /opt/oracle/instantclient234 |
| Oracle Config Directory | Apenas thick — local do tnsnames.ora | /opt/oracle/network/admin |

Exemplos de Connection String:

Oracle XE (local)
localhost:1521/XEPDB1
Oracle Enterprise
oracle-server.empresa.com:1521/PROD
Oracle Autonomous (OCI)
adb.us-ashburn-1.oraclecloud.com:1522/service_high.adb.oraclecloud.com
Oracle RDS (AWS)
mydb.cluster-xyz.us-east-1.rds.amazonaws.com:1521/ORCL
TNS alias (thick mode com tnsnames.ora)
MEUTNSALIAS

—

Thin vs Thick Mode — Quando Usar Cada Um

Thin Mode

Thick Mode

Use Thick quando precisar de:

> Importante: O oracledb inicializa o modo do driver uma vez por processo. Se a primeira conexão no processo do n8n for Thin, todas as conexões subsequentes naquele processo também serão Thin. Para garantir o Thick mode, configure todas as credenciais como Thick Mode — ou reinicie o n8n após alterar o modo.

—

Troubleshooting

Thin mode — conexão recusada

Thick mode — DPI-1047 (Oracle Client não encontrado)

Thick mode — DPI-1072 (já inicializado)

—

Desenvolvimento

npm install          # Instalar dependências
npm run build        # Compilar TypeScript
npm run dev          # Modo watch
npm run lint         # Verificar ESLint
npm run lint:fix     # Corrigir ESLint automaticamente

—

Contribuição

1. Fork o repositório
2. Crie uma branch para a feature
3. Implemente as mudanças e rode npm run build
4. Abra um Pull Request

—

Apoie o Projeto

—

Licença

MIT — veja LICENSE.md

—

Autor

Jônatas Meireles Sousa Vieira
Email: jonatas.mei@outlook.com
GitHub: @jonales
LinkedIn: jonatasmeireles

—