node-oracledb

node-oracledb is Oracle Corporation’s official Node.js add-on for connecting JavaScript and TypeScript applications to Oracle Database. Since version 6.0 it runs in “Thin mode” by default — a pure JavaScript implementation of the Oracle Net protocol that connects straight to the database with no external client libraries — while an optional “Thick mode” native binding unlocks additional legacy and advanced features by loading Oracle Instant Client.

Beyond standard SQL and PL/SQL execution, it exposes Oracle-specific capabilities as first-class APIs: SODA for NoSQL-style JSON document access, Oracle Advanced Queuing for message queues, connection pooling with detailed statistics, LOB streaming, and pipelined operations for reduced round-trips. The project ships zero runtime dependencies, maintains an extensive Mocha test suite, and is maintained directly by Oracle.

What You Get

• Direct Thin-mode connectivity to Oracle Database with zero external client libraries required
• Optional Thick mode for advanced or legacy features via Oracle Instant Client
• Full SQL and PL/SQL execution support with bind variables, batch operations, and streaming result sets
• SODA (Simple Oracle Document Access) for NoSQL-style JSON document storage and queries
• Oracle Advanced Queuing (AQ) support for message-queue based integrations
• Connection pooling with built-in statistics and health monitoring

Common Use Cases

• Connecting Node.js backends to an existing Oracle Database for transactional CRUD workloads
• Running PL/SQL stored procedures and functions from Node.js services
• Building document-store style applications on Oracle Database via SODA instead of a separate NoSQL database
• Implementing asynchronous, queue-based integrations using Oracle AQ
• Streaming large result sets or LOBs (CLOB/BLOB) without loading them fully into memory
• High-availability connection pooling for multi-tenant or cloud-native (OCI) deployments

Under The Hood

Architecture node-oracledb has a dual-mode architecture: Thin mode (pure JavaScript, lib/thin/) implements the Oracle Net (SQL*Net/TTC) wire protocol directly in lib/thin/protocol/ and lib/thin/sqlnet/, needing no Oracle Client libraries, while Thick mode is a native Node-API C++ addon (src/*.c, entry point njsModule.c) binding to the bundled ODPI-C library (odpi/), which wraps the Oracle Call Interface (OCI). The public API surface (lib/oracledb.js) is a facade that normalizes options and settings (settings.js) then delegates through an implementation-abstraction layer (lib/impl/) that dispatches to either the thin or thick backend depending on the active mode. Core domain objects — Connection, Pool, ResultSet, Lob, DbObject, SodaDatabase/Collection/Document, AqQueue — each have a thin JS implementation and, where applicable, a native-bound counterpart behind the same interface, with error codes centralized in errors.js as codified ERR_* constants.

Tech Stack The package declares zero runtime dependencies — the driver, including the Oracle Net wire protocol and TTC data marshaling, is implemented from scratch in JavaScript for Thin mode. Thick mode compiles a native addon via binding.gyp/node-gyp against the bundled ODPI-C sources, which call into Oracle Call Interface and the optional Oracle Instant Client at runtime (not build time). Testing uses Mocha with a dedicated config (test/opts/.mocharc.yaml), linting uses ESLint’s flat-config format, and dedicated build scripts (package/buildbinary.js, package/buildpackage.js) produce prebuilt native binaries across platforms and Node ABI versions.

Code Quality The test suite spans hundreds of files organized by feature area — AQ, SODA, bind types, pooling, streaming, and edge cases such as accessing properties on closed objects or async stack traces. Error handling is centralized and typed through errors.js’s catalogue of ERR_* codes, with explicit errors.assert/assertParamPropValue guards validating parameters at the API boundary throughout lib/oracledb.js, rather than ad hoc throws. Naming is consistent camelCase with descriptive option names, and the ESLint flat config enforces indentation, spacing, prefer-const, and other style rules. There is no compile-time type system (plain JavaScript, not TypeScript), so type safety relies on these runtime assertions rather than static types.

What Makes It Unique The standout technical choice is implementing the Oracle Net/TTC wire protocol natively in JavaScript for Thin mode — most enterprise database drivers require a native client library at runtime, but node-oracledb ships a pure-JS driver that connects directly to Oracle Database with no external dependencies, while still offering an opt-in native Thick mode for advanced or legacy needs via a bundled ODPI-C layer. It also treats SODA (a NoSQL-style JSON document API) and Oracle Advanced Queuing as first-class JavaScript APIs, alongside connection pipelining for reduced round-trips — capabilities well beyond a typical CRUD driver.