{"id":17964,"library":"strong-oracle","title":"StrongLoop Oracle Database Driver","description":"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`.","status":"maintenance","version":"1.9.0","language":"javascript","source_language":"en","source_url":"git://github.com/strongloop/strong-oracle","tags":["javascript","database","db","oracle"],"install":[{"cmd":"npm install strong-oracle","lang":"bash","label":"npm"},{"cmd":"yarn add strong-oracle","lang":"bash","label":"yarn"},{"cmd":"pnpm add strong-oracle","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for underlying Oracle Call Interface (OCI) communication. Both Basic/Basic Lite and SDK packages are necessary.","package":"Oracle Instant Client","optional":false},{"reason":"Required on Linux systems for asynchronous I/O operations with Oracle Instant Client.","package":"libaio","optional":true}],"imports":[{"note":"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.","wrong":"import oracle from 'strong-oracle';","symbol":"strong-oracle module","correct":"const oracle = require('strong-oracle');"},{"note":"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.","wrong":"const { connect } = require('strong-oracle');","symbol":"oracle factory function","correct":"const oracle = require('strong-oracle')(settings);"}],"quickstart":{"code":"const oracle = require('strong-oracle')({});\n\nconst connectData = {\n  hostname: 'localhost',\n  port: 1521, // Default Oracle Listener port\n  user: 'test',\n  password: process.env.ORACLE_PASSWORD ?? 'test',\n  database: 'ORCL' // Service name or SID\n};\n\noracle.connect(connectData, function(err, connection) {\n  if (err) {\n    console.error('Failed to connect to Oracle:', err);\n    return;\n  }\n  console.log('Successfully connected to Oracle database!');\n\n  // Example: Execute a simple query\n  connection.execute('SELECT SYSDATE FROM DUAL', [], function(queryErr, result) {\n    if (queryErr) {\n      console.error('Error executing query:', queryErr);\n    } else {\n      console.log('Current database date:', result.rows[0].SYSDATE);\n    }\n\n    // Always close the connection when done\n    connection.close(function(closeErr) {\n      if (closeErr) {\n        console.error('Error closing connection:', closeErr);\n      } else {\n        console.log('Connection closed.');\n      }\n    });\n  });\n});","lang":"javascript","description":"Demonstrates connecting to an Oracle database using basic connection parameters, executing a simple query, and properly closing the connection."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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).","cause":"The `strong-oracle` package's native bindings cannot find or load the necessary Oracle Instant Client DLLs/shared objects.","error":"Error: NJS-045: cannot load the Oracle Instant Client libraries"},{"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`.","cause":"The Oracle database connection string or TNS alias provided is incorrect or cannot be resolved by the Instant Client.","error":"ORA-12154: TNS:could not resolve the connect identifier specified"},{"fix":"Install `libaio`: `sudo apt-get install libaio1` (Debian/Ubuntu) or `sudo yum install libaio` (Fedora/CentOS/RHEL).","cause":"The `libaio` library, required by Oracle Instant Client on Linux systems, is not installed.","error":"Error: Missing libaio.so.1"},{"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.","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.","error":"The specified module could not be found. (Windows, during `require('strong-oracle')`)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}