StrongLoop Oracle Database Driver

1.9.0 verified Thu Apr 23 auth: no javascript maintenance

The `strong-oracle` package is a Node.js driver for connecting to Oracle databases, leveraging Oracle's own Instant Client libraries. It allows Node.js applications to interact with Oracle databases by providing a thin wrapper around the Oracle Call Interface (OCI). As of version 1.9.0, it remains a CommonJS module. Its release cadence appears to be slow, with `1.x` being the primary stable branch, suggesting it is in maintenance mode rather than active feature development. A key differentiator is its reliance on a locally installed Oracle Instant Client, which requires careful manual setup of environment variables, symbolic links, and system libraries (like `libaio` on Linux) specific to the operating system and architecture. This direct OCI binding offers performance and features consistent with Oracle's native client, but introduces a significant pre-installation and configuration overhead compared to pure JavaScript drivers. The library supports various connection methods, including direct hostname/port, full TNS connection strings, and TNS aliases configured in `tnsnames.ora`.

Common errors

error Error: NJS-045: cannot load the Oracle Instant Client libraries ↓

cause The `strong-oracle` package's native bindings cannot find or load the necessary Oracle Instant Client DLLs/shared objects.

fix

Verify that Oracle Instant Client is correctly installed and the OCI_HOME, OCI_LIB_DIR, OCI_INCLUDE_DIR environment variables are set. On Linux, ensure LD_LIBRARY_PATH (or /etc/ld.so.conf.d/) is configured. On MacOS, check DYLD_LIBRARY_PATH. On Windows, confirm Path includes the Instant Client directories (with correct order).

error ORA-12154: TNS:could not resolve the connect identifier specified ↓

cause The Oracle database connection string or TNS alias provided is incorrect or cannot be resolved by the Instant Client.

fix

If using a database name, ensure it's a valid service name or SID. If using tns, verify the tnsnames.ora file is correctly configured, TNS_ADMIN environment variable points to its directory, and the alias exists and is spelled correctly. Try a full connection string directly in connectData.tns.

error Error: Missing libaio.so.1 ↓

cause The `libaio` library, required by Oracle Instant Client on Linux systems, is not installed.

fix

Install libaio: sudo apt-get install libaio1 (Debian/Ubuntu) or sudo yum install libaio (Fedora/CentOS/RHEL).

error The specified module could not be found. (Windows, during `require('strong-oracle')`) ↓

cause Native Node.js modules (like `strong-oracle`) or their dependencies (like Oracle's OCI DLLs) are not locatable in the system's `Path` or within the Node.js module resolution paths, often due to missing C++ runtimes or incorrect `Path` ordering.

fix

Ensure the Visual Studio C++ Redistributable version corresponding to your Node.js build (e.g., VS2012 for OCI 12.1 as per README) is installed. Double-check the Path environment variable, specifically the order of instantclient\vcXX and instantclient entries as described in the warnings.

Warnings

breaking Mismatch in system architecture (32-bit vs. 64-bit) between Node.js, your operating system, and the downloaded Oracle Instant Client packages will prevent `strong-oracle` from loading its native bindings, leading to runtime errors. ↓

fix Ensure that the Oracle Instant Client (Basic/Basic Lite and SDK) packages downloaded match your system's architecture (e.g., x64 for 64-bit Node.js and OS). Reinstall if necessary.

gotcha Oracle Instant Client and `libaio` (on Linux) are mandatory external dependencies that must be manually installed and configured. Incorrect setup of environment variables (`OCI_HOME`, `OCI_LIB_DIR`, `OCI_INCLUDE_DIR`, `LD_LIBRARY_PATH`/`DYLD_LIBRARY_PATH`/`Path`) or missing symbolic links can cause 'module not found' or OCI initialization errors. ↓

fix Refer to the package README for detailed, OS-specific installation instructions for Oracle Instant Client and `libaio`. Double-check all environment variables, symbolic links, and dynamic library paths according to your OS.

gotcha On Windows, the order of directories in the `Path` environment variable is critical. The `vc11` or `vc10` subdirectory of `instantclient` must appear *before* the main `instantclient` directory to ensure the correct Visual Studio runtime libraries are loaded. ↓

fix Edit your system's `Path` environment variable. For example, `C:\instantclient_12_1\vc11;C:\instantclient_12_1` ensures correct DLL resolution. Restart your shell or IDE after changes.

gotcha The `strong-oracle` driver defaults to OCI v12 (v11 on Mac OS X). If your Oracle Instant Client version differs and causes compatibility issues, you may need to explicitly set the `oci_version` via `GYP_DEFINES`. ↓

fix Before installing `strong-oracle`, set `export GYP_DEFINES="oci_version=11"` (for bash/zsh) or `set GYP_DEFINES="oci_version=11"` (for Windows cmd) to match your Instant Client version, then reinstall the package (`npm rebuild strong-oracle`).

Install

npm install strong-oracle

yarn add strong-oracle

pnpm add strong-oracle

Imports

strong-oracle module
wrong
```
import oracle from 'strong-oracle';
```
correct
```
const oracle = require('strong-oracle');
```
This package is a CommonJS module. Direct ES module `import` syntax is not supported without a transpilation step or Node.js's CJS-to-ESM interop features which treat it as a default export.
oracle factory function
wrong
```
const { connect } = require('strong-oracle');
```
correct
```
const oracle = require('strong-oracle')(settings);
```
The `strong-oracle` module exports a function that must be called with an optional `settings` object to get the actual API object, not direct named exports.

Quickstart

Demonstrates connecting to an Oracle database using basic connection parameters, executing a simple query, and properly closing the connection.

const oracle = require('strong-oracle')({});

const connectData = {
  hostname: 'localhost',
  port: 1521, // Default Oracle Listener port
  user: 'test',
  password: process.env.ORACLE_PASSWORD ?? 'test',
  database: 'ORCL' // Service name or SID
};

oracle.connect(connectData, function(err, connection) {
  if (err) {
    console.error('Failed to connect to Oracle:', err);
    return;
  }
  console.log('Successfully connected to Oracle database!');

  // Example: Execute a simple query
  connection.execute('SELECT SYSDATE FROM DUAL', [], function(queryErr, result) {
    if (queryErr) {
      console.error('Error executing query:', queryErr);
    } else {
      console.log('Current database date:', result.rows[0].SYSDATE);
    }

    // Always close the connection when done
    connection.close(function(closeErr) {
      if (closeErr) {
        console.error('Error closing connection:', closeErr);
      } else {
        console.log('Connection closed.');
      }
    });
  });
});