# node-oracledb: the Oracle Database driver for Node.js, thin mode and all > Oracle's official Node.js add-on connects JavaScript and TypeScript applications to Oracle Database. It installs with one npm command, runs in thin mode without Oracle Client libraries, and switches to thick mode when you need features the pure-JavaScript path does not cover. **oracle/node-oracledb** — Oracle Database driver for Node.js maintained by Oracle Corporation. Connect your JavaScript and TypeScript applications instantly to Oracle Database. - Repository: https://github.com/oracle/node-oracledb - Website: http://oracle.github.io/node-oracledb/ - Stars: 2,369 · Forks: 1,074 - Language: JavaScript - License: NOASSERTION - Published: 2026-09-28 · Updated: 2026-09-28 · Language: en - Canonical page: https://hysenlabs.com/projects/oracle-node-oracledb ## The gap node-oracledb fills for JavaScript and TypeScript teams Node.js ships with no database driver at all, and Oracle Database speaks its own wire protocol rather than the MySQL or PostgreSQL one. A team with an Oracle estate and a Node.js service has three options: shell out to a command-line client, run a separate service in another language, or use a driver that implements the protocol. node-oracledb is the third option, and it is maintained by Oracle Corp. rather than by a third party. The README describes it as an add-on that "powers high performance Oracle Database applications", with applications written in TypeScript or directly in JavaScript. The package keywords list SQL, PL/SQL, SODA, JSON and OCI, which is a fair summary of the surface area: this is not a thin query wrapper. The stated feature set covers SQL and PL/SQL execution, fast data ingestion, NoSQL-style document APIs, message queueing, database notifications, and starting and stopping the database. Database operations can optionally be pipelined, which the documentation links to a dedicated pipeline page. The audience is narrower than the feature list suggests. If you are writing a Node.js service against an Oracle Database, this is the official path and the one most ORMs, SQL generators and libraries build on. If you are not on Oracle, nothing here applies to you. ## Thin mode versus thick mode: the architecture decision that shapes everything From version 6.0 onward, node-oracledb runs by default in what the README calls thin mode: it connects directly to Oracle Database with no Oracle Client libraries present. This is the single biggest change in the project's history, because older versions of node-oracledb required Oracle Client libraries before a connection was possible. The README states this plainly: Oracle Client libraries are optional starting from node-oracledb 6.0, and older versions require them. Thick mode is the alternative. When optional Oracle Client libraries are loaded, node-oracledb uses them, and some advanced Oracle Database functionality is only available that way. The README does not enumerate which features require thick mode in the text available here; it points to the homepage for the feature list, so treat that page as the source of truth before designing around thin mode. The version floors differ between the two modes, which matters when you are sizing a migration. Thin mode requires Oracle Database 12.1 or later. Thick mode requires Oracle Database 11.2 or later, depending on the Oracle Client library version, and node-oracledb can use Oracle Client libraries version 19 or later. The README notes that Oracle Database's standard client-server version interoperability allows connection to both older and newer databases, giving the example that Oracle Client 19c libraries can connect to Oracle Database 11.2 or later. So a legacy 11.2 database is reachable, but only through thick mode. ## Installing node-oracledb and running a first query The README gives a single installation command. There is no build step for the common case, because pre-built packages are published on npm and other mirror repositories. ```bash npm install oracledb ``` After that, a connection in thin mode needs only credentials and a connect string. The repository ships an examples directory, and the README points readers to examples/example.js as the starting point. The examples directory also contains connect.js and connectionpool.js, which are the files to read if you want a working connection and pool setup rather than a minimal one. The README does not print a connection code sample in the text available here, so the safest first run is the shipped example itself. Fetch it and execute it against your database, then read it to see how the module's connection entry points are called. ```bash node examples/example.js ``` If you need thick mode, you install Oracle Instant Client separately. The README describes the Instant Client packages as free and states that node-oracledb can use Oracle Client libraries version 19 or later. Installation details for that path live in INSTALL.md in the repository root, not in the README body. The package requires Node.js 14.17 or later, and package.json encodes that as engines: node >=14.17. The README notes that older versions of node-oracledb may work with older versions of Node.js, which is the escape hatch if you are pinned to an old runtime. ## Where node-oracledb is the wrong choice The clearest limitation is scope: this module talks to Oracle Database. If your data lives in PostgreSQL, MySQL, SQL Server or a document store, node-oracledb cannot help, and no amount of configuration changes that. The package keywords and the README both describe Oracle Database access specifically. The second limitation is the thin mode ceiling. The README states that some advanced Oracle Database functionality is currently only available when Oracle Client libraries are loaded. That word "currently" is doing real work: thin mode is the default, but it is not yet a complete replacement for the client library path. A team that adopts thin mode for deployment simplicity may still find itself installing Oracle Instant Client later for a specific feature, which means the operational cost you thought you avoided can return mid-project. The third is version floors. Thin mode needs Oracle Database 12.1 or later. If you are on 11.2, you are in thick mode by definition, and you inherit the Instant Client dependency plus the client-server interoperability rules. The README's example (Oracle Client 19c against Oracle Database 11.2 or later) shows this works, but it is a different deployment shape than the default. Finally, the README you are reading describes version 7.1.0-dev and carries the warning that the release is under development and information may be incomplete. That is the development branch's own disclaimer. If you are making a production decision, read the release notes for the version you actually intend to install rather than the in-development README. ## node-oracledb compared with a generic SQL client and with the Python driver The obvious alternative for a JavaScript team is a generic SQL client that speaks a common protocol, or an ORM that abstracts the database behind a query builder. The difference is protocol reach. Generic clients rely on database-specific dialects or adapters, and Oracle's wire protocol is not what they target first. node-oracledb implements Oracle's protocol directly, which is why the README can list PL/SQL, SODA document APIs, advanced queueing, continuous query notification and database start/stop as supported. A generic client would need an Oracle adapter that eventually calls something like node-oracledb anyway. The other real alternative is Oracle's own driver for another runtime, most commonly python-oracledb. The architectural parallel is close: python-oracledb also moved to a thin mode that removes the client library requirement, and both are maintained by Oracle. The difference is the ecosystem around them, not the database access. If your service is already Node.js, switching runtimes to get a driver is a larger change than the driver itself. If your team is polyglot and the Oracle access layer is small, a Python service using python-oracledb is a legitimate design, but you have then added a network hop and a second deployment to maintain. Within Node.js, the meaningful comparison is node-oracledb against an ORM layered on top of it. The ORM gives you migrations, relations and typed models; node-oracledb gives you the statement execution, pooling and ingestion primitives those ORMs are built from. The README notes the module "is used by many JavaScript and TypeScript frameworks, SQL generators, ORMs, and libraries", which is the honest framing: choosing the driver does not preclude choosing an ORM, it determines what sits underneath. ## Maintenance cadence, versioning and the dual licence The repository is not archived, and the last push was on 2026-08-12. Recent releases are v7.0.1 on 2026-07-15, v7.0.0 on 2026-06-01, and v6.10.0 on 2025-10-16. The gap between 6.10.0 and 7.0.0 is roughly seven and a half months, and 7.0.1 followed six weeks after 7.0.0. That is a cadence with long minor cycles punctuated by quick patch releases, which is what you would expect from a driver tied to database and client library versions. The upgrade cost is mostly version-floor management. Node.js 14.17 is the current floor in package.json, and the README notes that older node-oracledb versions supported older Node.js versions and older Client versions. Moving forward in node-oracledb can raise your Node.js floor, your Oracle Client floor, or your database floor, depending on which mode you run. The CHANGELOG.md and release notes are the files to read before an upgrade, and INSTALL.md covers the installation side. On licensing: the README states the software is dual-licensed under the Universal Permissive License 1.0 and Apache License 2.0, and that you may choose either. package.json encodes this as license: "(Apache-2.0 OR UPL-1.0)". There is also a NOTICE.txt and a THIRD_PARTY_LICENSES.txt in the repository root, which is where the bundled components' terms live. Whether either licence fits your organisation's policy is a question for your legal team; the repository gives you the identifiers, not the answer. Note that the Oracle Instant Client, which thick mode requires, is a separate Oracle download with its own terms, and the README describes it as free rather than as open source. ## Conclusion Adopt node-oracledb if your application already lives in Node.js and talks to Oracle Database, especially if you want thin mode and no client library installation. Do not adopt it if your database is PostgreSQL, MySQL or SQL Server; the module only speaks to Oracle. Before committing, verify that your target database version clears the thin mode floor of Oracle Database 12.1, and confirm which advanced features force you into thick mode and the Oracle Instant Client download that comes with it. ## FAQ ### Can I use Node.js with SQL? Yes. node-oracledb is the Oracle-maintained Node.js add-on for Oracle Database, and the README states that it gives you control over SQL and PL/SQL statement execution. It requires Node.js 14.17 or later. ### What is OracleDB? Oracle Database is the database that node-oracledb connects to. The README describes the add-on as powering high performance Oracle Database applications, and thin mode requires Oracle Database 12.1 or later. ### Is Node.js still in demand? The README frames node-oracledb around Node.js 14.17 or later, and notes that the module is used by many JavaScript and TypeScript frameworks, SQL generators, ORMs and libraries. It does not make any claim about overall demand for Node.js. ### What is Node.js and why is it used? node-oracledb treats Node.js as the runtime for the add-on: the README states it connects Node.js 14.17 or later to Oracle Database, and that applications can be written in TypeScript or directly in JavaScript. It does not explain what Node.js is beyond that. ## Sources - [Issues](https://github.com/oracle/node-oracledb/issues) - [oracle/node-oracledb on GitHub](https://github.com/oracle/node-oracledb) - [Project website](http://oracle.github.io/node-oracledb/) - [README](https://github.com/oracle/node-oracledb/blob/main/README.md) - [Releases](https://github.com/oracle/node-oracledb/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oracle-node-oracledb