2. Installing node-oracledb — node-oracledb 6.8.0 documentation (original) (raw)
By default, the node-oracledb driver is a pure JavaScript module that directly connects to Oracle Database 12.1 or later. This ‘Thin’ mode does not need Oracle Client libraries. The database can be on the same machine as Node.js, or it can be remote.
Pre-built ‘Thick’ mode binaries for common architectures (Windows 64-bit, Linux x86_64, Linux ARM (aarch64), and macOS Intel) are included in the node-oracledb installation as a convenience. Thick mode provides some additional functionality. To use Thick mode, Oracle Client libraries version 11.2, or later, need to be manually installed. Node-oracledb Thick mode can connect to Oracle Database 9.2 or later, depending on the Oracle Client library version. Note the operating systems and versions of Node.js that the pre-built node-oracledb binaries are compatible with will change as the Node.js project evolves. The binaries are not guaranteed to be available or usable in your environment. The Thick mode binary may additionally build from available C source code on other platforms like Windows 32-bit, Solaris, and AIX environments. See Installing node-oracledb from Source Code.
2.1. Quick Start node-oracledb Installation
Simple installation instructions for Windows, macOS, and Linux are available:
- Quick Start: Developing Node.js Applications for Oracle Database
- Quick Start: Developing Node.js Applications for Oracle Autonomous Database
Alternatively, follow these instructions:
- Install Node.js from nodejs.org.
- Add
oracledb
to yourpackage.json
dependencies or run:
This installs from the npm registry.
If you are behind a firewall, you may need to set the proxy with a command likenpm config set proxy http://myproxy.example.com:80/
. - Download the node-oracledb examples or alternatively create a script like myscript.js ormysoda.js as given below.
- Locate your Oracle Database user name and password, and the databaseconnection string. The connection string is commonly of the format
hostname/servicename
, using the host name where the database is running and the Oracle Database service name of the database instance. For example,localhost/FREEPDB1
. - Substitute your user name, password, and connection string in the code. For downloaded examples, put these in dbconfig.js or set the relevant environment variables.
- Run the script, for example:
If you run into installation trouble, see Troubleshooting Errors.
2.1.1. Example: A SQL SELECT statement in Node.js
// myscript.js
const oracledb = require('oracledb');
oracledb.outFormat = oracledb.OUT_FORMAT_OBJECT;
const mypw = ... // set mypw to the hr schema password
async function run() {
const connection = await oracledb.getConnection ({
user : "hr",
password : mypw,
connectString : "localhost/FREEPDB1"
});
const result = await connection.execute(
`SELECT manager_id, department_id, department_name
FROM departments
WHERE manager_id = :id`,
[103], // bind value for :id
);
console.log(result.rows);
await connection.close();
}
run();
With Oracle’s sample HR schema, the output is:
[ { MANAGER_ID: 103, DEPARTMENT_ID: 60, DEPARTMENT_NAME: 'IT' } ]
This example uses Async/Await syntax. Node-oracledb can also use Callbacks, andPromises.
2.1.2. Example: Simple Oracle Document Access (SODA) in Node.js
Node-oracledb’s SODA API can be used for document-style access with Oracle Database 18 and above when node-oracledb Thick mode uses Oracle Client 18.5 or Oracle Client 19.3 (or later) libraries. Users require the database CREATE TABLE privilege and the SODA_APP role.
// mysoda.js
const oracledb = require('oracledb');
let clientOpts = {}; if (process.platform === 'win32') { // Windows clientOpts = { libDir: 'C:\oracle\instantclient_19_18' }; } else if (process.platform === 'darwin' && process.arch === 'x64') { // macOS Intel clientOpts = { libDir: process.env.HOME + '/Downloads/instantclient_19_8' }; } // else on other platforms the system library search path // must always be set before Node.js is started.
// enable Thick mode which is needed for SODA oracledb.initOracleClient(clientOpts);
const mypw = ... // set mypw to the hr schema password
oracledb.autoCommit = true;
async function run() { connection = await oracledb.getConnection( { user : "hr", password : mypw, connectString : "localhost/orclpdb1" });
// Create a new (or open an existing) document collection
const soda = connection.getSodaDatabase();
const collectionName = 'nodb_soda_collection';
const myCollection = await soda.createCollection(collectionName);
// Insert a new document
const myContent = { name: "Sally", address: {city: "Melbourne"} };
await myCollection.insertOne(myContent);
// Print names of people living in Melbourne
const filterSpec = { "address.city": "Melbourne" };
const myDocuments = await myCollection.find().filter(filterSpec).getDocuments();
myDocuments.forEach(function(element) {
const content = element.getContent();
console.log(content.name + ' lives in Melbourne.');
});
await connection.close();
}
run();
Output is:
Sally lives in Melbourne.
2.2. Supported Oracle Database Versions
When node-oracledb is used in the default Thin mode, it connects directly to the Oracle Database and does not require Oracle Client libraries. Connections in this mode can be made to Oracle Database 12.1 or later.
When node-oracledb is in Thick mode using Oracle Client libraries, connections can be made to Oracle Database 9.2, or later, depending on the Oracle Client library version.
Oracle’s standard client-server network interoperability allows connections between different versions of Oracle Client libraries and Oracle Database. For currently certified configurations, see Oracle Support’s Doc ID 207303.1. In summary:
- Oracle Client 23 can connect to Oracle Database 19 or later
- Oracle Client 21 can connect to Oracle Database 12.1 or later
- Oracle Client 19, 18, and 12.2 can connect to Oracle Database 11.2 or later
- Oracle Client 12.1 can connect to Oracle Database 10.2 or later
- Oracle Client 11.2 can connect to Oracle Database 9.2 or later
Not all features are available in all versions or driver modes. Any attempt to use Oracle features that are not supported by a particular mode or client library/database combination will result in runtime errors.The node-oracledb attributes oracledb.thin, pool.thin andconnection.thin can be used to see what mode a connection is in. In the Thick mode, the attribute oracledb.oracleClientVersion can be used to determine which Oracle Client version is in use. The attributeconnection.oracleServerVersionString can be used to determine which Oracle Database version a connection is accessing. These attributes can be used to adjust application feature usage appropriately.
2.3. Installation Requirements
To use node-oracledb, you need:
- Node.js 14.6 or later.
- Access to an Oracle Database either local or remote, on-premises, or in theCloud. You will need to know the database credentials and theconnection string for the database.
Installing node-oracledb does not install or create a database. - Optionally, Oracle Client libraries can be installed to enable thenode-oracledb Thick mode which has someadditional functionality. These libraries can be:
- from the free Oracle Instant Client, or
- from a full Oracle Client installation (such as installed by Oracle’s GUI installer), or
- from those included in Oracle Database if Node.js is on the same machine as the database
Oracle Client libraries versions 23, 21, 19, 18, 12, and 11.2 are supported where available on Linux, Windows, and macOS. Oracle’s standard client-server version interoperability allows connection to both older and newer databases.
Runnode -p "process.arch"
to identify the Node.js architecture so that you can install the appropriate 64-bit or 32-bit Oracle Client libraries.
2.4. Installing Node.js and node-oracledb on Linux
Review the Installation Requirements.
2.4.1. Install Node.js
- Download and extract the Node.js “Linux Binaries”package. For example, if you downloaded version 18.16.0 for 64-bit you could install Node.js into
/opt
:
cd /opt
tar -Jxf node-v18.16.0-linux-x64.tar.xz - Set
PATH
to include Node.js:
export PATH=/opt/node-v18.16.0-linux-x64/bin:$PATH
2.4.2. Install node-oracledb
- Install node-oracledb using the
npm
package manager, which is included in Node.js:
This will download and install node-oracledb from the npm registry.
If you are behind a firewall, then you may need to set your proxy first before installing node-oracledb, for example:
npm config set proxy http://myproxy.example.com:80/ - You can now run applications.
Runnable samples are available from GitHub. To try them follow these steps:- Download the examples.
- Edit
dbconfig.js
and set the database credentials to your environment, for example:
module.exports = {
user : "hr",
password : process.env.NODE_ORACLEDB_PASSWORD,
connectString : "localhost/FREEPDB1"
}; - Run one of the examples, such as example.js:
- If you want to use node-oracledb Thick mode featuresin your application, then follow the instructions in thenext section. Otherwise, if you will only ever use Thin mode, you can optionally minimize the install footprint by removing all the Thick mode binaries automatically installed with node-oracledb. To remove the binaries, run commands like:
cd node_modules/oracledb
npm run prune all
This can be automated with apostinstall
script in yourpackage.json
file:
"scripts": {
"postinstall": "cd node_modules/oracledb && npm run prune all"
},
Questions can be asked as GitHub Discussions.
2.4.3. Install Oracle Client to use Thick Mode
By default, the node-oracledb driver is a pure JavaScript module that runs in a Thin mode connecting directly to Oracle Database so no further installation steps are required. However, to use additional node-oracledb features available in Thick mode, you need to install Oracle Client libraries. Oracle Client versions 23, 21, 19, 18, 12, and 11.2 are supported. Thick mode uses a binary add-on installed with node-oracledb that loads these Oracle Client libraries.
Depending on whether your database is on the same machine as Node.js or remote, you may need to adjust the Oracle Client installation instructions:
- If your database is on a remote computer, then download the free Oracle Instant Client “Basic” or “Basic Light” package for your operating system architecture and if your Linux distribution:
- Uses the Debian package format, then follow the instructions inOracle Instant Client ZIP Files
- Or uses RPM packages, then follow the instructions in Oracle Instant Client RPMs
- Alternatively, use the client libraries already available in a locally installed database such as the free Oracle Database Free release (previously known as Oracle Database Express Edition (“XE”)) and follow the instructions in Local Database or Full Client.
For Linux x86_64, the pre-built node-oracledb binary was built on Oracle Linux 8 and requires glibc 2.14 version or later. For Linux ARM (aarch64), the binary was built on Oracle Linux 8. If you want to use Thick mode but a pre-built binary is not available for your architecture, you will need tocompile node-oracledb from source code.
If you have multiple copies of Oracle Client libraries installed, check if the expected version is first in LD_LIBRARY_PATH
.
If you need system privileges to set, or preserve, variables like PATH
, you can use sudo -E
on Linux.
On Linux, do not pass the libDir
attribute tooracledb.initOracleClient(). The Oracle Client libraries on Linux_must_ be in the system library search path before the Node.js process starts.
2.4.3.1. Oracle Instant Client ZIP Files
Follow these steps if your database is on a remote machine and either:
- you prefer installing Instant Client ZIP files instead ofRPM packages
- or your Linux distribution uses the Debian package format, for example if you are using Ubuntu. Note: you should review Oracle’s supported distributions before choosing an operating system.
To use node-oracledb Thick mode with Oracle Instant Client zip files:
- Download an Oracle 23, 21, 19, 18, 12, or 11.2 “Basic” or “Basic Light” zip file matching your architecture:
- Linux 64-bit (x86-64)
- Linux ARM 64-bit (aarch64)
Oracle Instant Client 23ai will connect to Oracle Database 19 or later. Oracle Instant Client 21c will connect to Oracle Database 12.1 or later. Oracle Instant Client 19c will connect to Oracle Database 11.2 or later.
It is recommended to keep up to date with the latest Oracle Instant Client release updates of your desired major version. Oracle Database 23ai and 19c are Long Term Support Releases whereas Oracle Database 21c is an Innovation Release.
- Unzip the package into a directory accessible to your application, for example:
mkdir -p /opt/oracle
cd /opt/oracle
wget https://download.oracle.com/otn_software/linux/instantclient/instantclient-basic-linuxx64.zip
unzip instantclient-basic-linuxx64.zip
Note: OS restrictions may prevent the opening of Oracle Client libraries installed in unsafe paths, such as from a user directory. You may need to install under a directory like/opt
or/usr/local
. - Install the
libaio
package. On some platforms the package is calledlibaio1
. Depending on your Linux distribution package manager, run a command like:
or:
apt-get install -y libaio1
When using Oracle Instant Client 19 on recent Linux versions such as Oracle Linux 8, you may need to manually install thelibnsl
package to makelibnsl.so
available. This package is not needed from Oracle Instant Client 21 and later. - If there is no other Oracle software on the machine that will be impacted, then permanently add Instant Client to the run-time link path. For example, if the Basic package is unzipped to
/opt/oracle/instantclient_19_18
, then run the following using sudo or as the root user:
sudo sh -c "echo /opt/oracle/instantclient_19_18 > /etc/ld.so.conf.d/oracle-instantclient.conf"
sudo ldconfig
Alternatively, set the environment variableLD_LIBRARY_PATH
to the appropriate directory for the Instant Client version. For example:
export LD_LIBRARY_PATH=/opt/oracle/instantclient_19_18:$LD_LIBRARY_PATH - Call oracledb.initOracleClient() in your application to enable Thick mode, see Enabling node-oracledb Thick Mode on Linux and Related Platforms.
- If you use the optional Oracle configuration files, seeUsing Optional Oracle Configuration Files.
If disk space is important, most users will be able to use the smaller Basic Light package instead of the Basic package. Review its globalization limitations. Disk space can be reduced by removing unnecessary libraries and files from either the Basic or Basic Light packages. The exact libraries depend on the Instant Client version. For example, with Oracle Instant Client 19, you can optionally remove files using:
rm -i jdbc occi mysql mql1 ipc1 *jar uidrvci genezi adrci
Refer to the Oracle Instant Client documentation for details.
2.4.3.2. Oracle Instant Client RPMs
Follow these steps if your database is on a remote machine and your Linux distribution uses RPM packages. Also see Installing Node.js and node-oracledb RPMs from yum.oracle.com.
To use node-oracledb with Oracle Instant Client RPMs:
- Download an Oracle 23, 21, 19, 18, 12, or 11.2 “Basic” or “Basic Light” RPM matching your architecture:
- Install the downloaded RPM with sudo or as the root user. For example:
sudo yum install oracle-instantclient19.18-basic-19.18.0.0.0-1.x86_64.rpm
You can install directly from yum.oracle.com, for example using:
sudo yum -y install oracle-release-el8
sudo yum-config-manager --enable ol8_oracle_instantclient
sudo yum -y install oracle-instantclient19.18-basic
If you have a ULN subscription, another alternative is to useyum
to install the Basic package after enabling the ol7_x86_64_instantclient or ol6_x86_64_instantclient repository, depending on your version of Linux.
Yum automatically installs required dependencies, such aslibaio
package.
When using Oracle Instant Client 19 on recent Linux versions such as Oracle Linux 8, you may need to manually install thelibnsl
package to makelibnsl.so
available. This package is not needed from Oracle Instant Client 21 onward. - For Instant Client 19 RPMs, the system library search path is automatically configured during installation.
For older versions, if there is no other Oracle software on the machine that will be impacted, then permanently add Instant Client to the run-time link path. For example, with sudo or as the root user:
sudo sh -c "echo /usr/lib/oracle/18.3/client64/lib > /etc/ld.so.conf.d/oracle-instantclient.conf"
sudo ldconfig
Alternatively, for version 18 and earlier, every shell running Node.js will need to have the link path set:
export LD_LIBRARY_PATH=/usr/lib/oracle/18.3/client64/lib - Call oracledb.initOracleClient() in your application to enable Thick mode, see Enabling node-oracledb Thick Mode on Linux and Related Platforms.
- If you use the optional Oracle configuration files, seeUsing Optional Oracle Configuration Files.
2.4.3.3. Local Database or Full Client
Follow these steps if you are running Node.js on the same machine where Oracle Database is installed.
The ORACLE_HOME
can be either a database home or a full Oracle client installation installed with Oracle’s runInstaller
.
For easy development, Oracle Database Free is available on Linux. Applications developed with this database may be immediately used with other editions of the Oracle Database.
To use node-oracledb with local database or full client:
- Set required Oracle environment variables, such as
ORACLE_HOME
andLD_LIBRARY_PATH
by executing:
source /usr/local/bin/oraenv
Or, if you are using Oracle XE 11.2, by executing:
source /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh
Ensure that the Node.js process has directory and file access permissions for the Oracle Client libraries and other files. Typically the home directory of the Oracle software owner will need permissions relaxed. - Place the optional Oracle client configuration files such astnsnames.ora, sqlnet.ora, and oraaccess.xml as detailed inUsing Optional Oracle Configuration Files.
- Call oracledb.initOracleClient() in your application to enable Thick mode, see Enabling node-oracledb Thick Mode on Linux and Related Platforms.
2.4.4. Installing Node.js and node-oracledb RPMs from yum.oracle.com
Node.js and node-oracledb Linux RPM packages are available onyum.oracle.com. See Node.js for Oracle Linux for installation details.
2.5. Installing Node.js and node-oracledb on Apple macOS
Review the generic Installation Requirements.
Note there is no native Oracle Database for macOS but you can connect to a remote database. Alternatively a database can easily be run in Docker or in a Linux virtual machine using Vagrant. See the Oracle Database Vagrant projects.
2.5.1. Install Node.js
Download the Node.js package for macOS and install it.
2.5.2. Install node-oracledb
- Install node-oracledb using the
npm
package manager, which is included in Node.js:
If you are behind a firewall, then you may need to set your proxy first before installing node-oracledb, for example:
npm config set proxy http://myproxy.example.com:80/ - You can now run applications.
Runnable samples are available from GitHub. To try them follow these steps:- Download the examples.
- Edit
dbconfig.js
and set the database credentials to your environment, for example:
module.exports = {
user : "hr",
password : process.env.NODE_ORACLEDB_PASSWORD,
connectString : "localhost/FREEPDB1"
}; - Run one of the examples, such as example.js:
- If you want to use node-oracledb Thick mode featuresin your application, then follow the instructions in thenext section. Otherwise, if you will only ever use Thin mode, you can optionally minimize the install footprint by removing all the Thick mode binaries automatically installed with node-oracledb. To remove the binaries, run commands like:
cd node_modules/oracledb
npm run prune all
This can be automated with apostinstall
script in yourpackage.json
file:
"scripts": {
"postinstall": "cd node_modules/oracledb && npm run prune all"
},
Questions can be asked as GitHub Discussions.
2.5.3. Install Oracle Client to use Thick Mode
By default, the node-oracledb driver is a pure JavaScript module that runs in a Thin mode connecting directly to Oracle Database so no further installation steps are required. However, to use additional node-oracledb features available in Thick mode, you need to install Oracle Client libraries. Thick mode uses a binary add-on installed with node-oracledb that loads these libraries. This binary is available for macOS Intel only.
You can get the libraries from either the Oracle Instant Client Basic orBasic Light package. The steps below show installing Basic.
2.5.3.1. Instant Client Scripted Installation on macOS ARM64
Instant Client installation can be scripted. Open a terminal window and run:
cd $HOME/Downloads curl -O https://download.oracle.com/otn_software/mac/instantclient/233023/instantclient-basic-macos.arm64-23.3.0.23.09.dmg hdiutil mount instantclient-basic-macos.arm64-23.3.0.23.09.dmg /Volumes/instantclient-basic-macos.arm64-23.3.0.23.09/install_ic.sh hdiutil unmount /Volumes/instantclient-basic-macos.arm64-23.3.0.23.09
Note you should use the latest DMG available.
If you have multiple Instant Client DMG packages mounted, you only need to runinstall_ic.sh
once. It will copy all mounted Instant Client DMG packages at the same time.
The Instant Client directory will be like$HOME/Downloads/instantclient_23_3
. Applications may not have access to the Downloads
directory, so you should move Instant Client somewhere convenient.
Call oracledb.initOracleClient() to enable Thick mode, seeEnabling node-oracledb Thick Mode on macOS.
If you use the optional Oracle configuration files, seeUsing Optional Oracle Configuration Files.
2.5.3.2. Instant Client Manual Installation on macOS ARM64
- Download the latest Instant Client Basic ARM64 package DMG from Oracle.
- Using Finder, double-click the DMG to mount it.
- Open a terminal window and run the install script in the mounted package, for example if you downloaded version 23.3:
/Volumes/instantclient-basic-macos.arm64-23.3.0.23.09/install_ic.sh
The Instant Client directory will be like$HOME/Downloads/instantclient_23_3
. Applications may not have access to theDownloads
directory, so you should move Instant Client somewhere convenient. - Using Finder, eject the mounted Instant Client package.
- Call oracledb.initOracleClient() to enable Thick mode, seeEnabling node-oracledb Thick Mode on macOS.
- If you use the optional Oracle configuration files, seeUsing Optional Oracle Configuration Files.
If you have multiple Instant Client DMG packages mounted, you only need to runinstall_ic.sh
once. It will copy all mounted Instant Client DMG packages at the same time.
2.5.3.3. Instant Client Scripted Installation on macOS Intel x86-64
Instant Client installation can be scripted. Open a terminal window and run:
cd $HOME/Downloads curl -O https://download.oracle.com/otn_software/mac/instantclient/1916000/instantclient-basic-macos.x64-19.16.0.0.0dbru.dmg hdiutil mount instantclient-basic-macos.x64-19.16.0.0.0dbru.dmg /Volumes/instantclient-basic-macos.x64-19.16.0.0.0dbru/install_ic.sh hdiutil unmount /Volumes/instantclient-basic-macos.x64-19.16.0.0.0dbru
Note you should use the latest DMG available.
If you have multiple Instant Client DMG packages mounted, you only need to runinstall_ic.sh
once. It will copy all mounted Instant Client DMG packages at the same time.
The Instant Client directory will be $HOME/Downloads/instantclient_19_16
. Applications may not have access to the Downloads
directory, so you should move Instant Client somewhere convenient.
Call oracledb.initOracleClient() to enable Thick mode, seeEnabling node-oracledb Thick Mode on macOS.
If you use the optional Oracle configuration files, seeUsing Optional Oracle Configuration Files.
2.5.3.4. Instant Client Manual Installation on macOS Intel x86-64
- Download the latest Instant Client Basic Intel 64-bit package DMG fromOracle.
- Using Finder, double-click the DMG to mount it.
- Open a terminal window and run the install script in the mounted package, for example:
/Volumes/instantclient-basic-macos.x64-19.16.0.0.0dbru/install_ic.sh
The Instant Client directory will be$HOME/Downloads/instantclient_19_16
. Applications may not have access to theDownloads
directory, so you should move Instant Client somewhere convenient. - Using Finder, eject the mounted Instant Client package.
- Call oracledb.initOracleClient() to enable Thick mode, seeEnabling node-oracledb Thick Mode on macOS.
- If you use the optional Oracle configuration files, seeUsing Optional Oracle Configuration Files.
If you have multiple Instant Client DMG packages mounted, you only need to runinstall_ic.sh
once. It will copy all mounted Instant Client DMG packages at the same time.
2.6. Installing Node.js and node-oracledb on Microsoft Windows
Review the Installation Requirements.
2.6.1. Install Node.js
Install the 64-bit Node.js MSI (for example, node-v18.16.0-x64.msi) fromnodejs.org. Make sure the option to add the Node.js and npm directories to the path is selected.
2.6.2. Install node-oracledb
- Open a terminal window.
- Install node-oracledb using the
npm
package manager, which is included in Node.js:
If you are behind a firewall, then you may need to set your proxy first before installing node-oracledb, for example:
npm config set proxy http://myproxy.example.com:80/ - You can now run applications.
Runnable samples are available from GitHub. To try them follow these steps:- Download the examples.
- Edit
dbconfig.js
and set the database credentials to your environment, for example:
module.exports = {
user : "hr",
password : process.env.NODE_ORACLEDB_PASSWORD,
connectString : "localhost/FREEPDB1"
}; - Run one of the examples, such as example.js:
- If you want to use node-oracledb Thick mode featuresin your application, then follow the instructions in thenext section. Otherwise, if you will only ever use Thin mode, you can optionally minimize the install footprint by removing all the Thick mode binaries automatically installed with node-oracledb. To remove the binaries, run commands like:
cd node_modules\oracledb
npm run prune all
This can be automated with apostinstall
script in yourpackage.json
file:
"scripts": {
"postinstall": "cd node_modules/oracledb && npm run prune all"
},
Questions can be asked as GitHub Discussions.
2.6.3. Install Oracle Client to use Thick Mode
By default, the node-oracledb driver is a pure JavaScript module that runs in a Thin mode connecting directly to Oracle Database so no further installation steps are required. However, to use additional features available inThick mode you need Oracle Client libraries installed. Oracle Client versions 21, 19, 18, 12, and 11.2 are supported. Thick mode uses a binary add-on installed with node-oracledb that loads these libraries.
Depending on whether your database is on the same machine as Node.js or remote, you may need to adjust the Oracle Client installation instructions:
- If your database is on a remote computer, then download the free Oracle Instant Client “Basic” or “Basic Light” package for your operating system architecture and follow the instructions in Oracle Instant Client ZIP Files.
- If your database is on a local machine, use the client libraries already available in a locally installed database such as the freeOracle Database Express Edition (“XE”) release and follow the instructions inLocal Database or Full Client.
If you have multiple copies of Oracle Client libraries installed, check if the expected version is first in PATH
.
If you need system privileges to set, or preserve, variables like PATH
, you can use an elevated command prompt on Windows.
2.6.3.1. Oracle Instant Client ZIP Files
Follow these steps if your database is on a remote machine, or if you already have Oracle software installed but you want node-oracledb to use a different version of the libraries.
The pre-built binaries were built with Visual Studio 2017 and require the matching redistributable.
You may need Administrator privileges to set environment variables or install software.
To use node-oracledb in Thick mode with Oracle Instant Client ZIP files:
- Download the free 64-bit Instant Client Basic ZIP file from Oracle Technology Network.
- Unzip the ZIP file into a directory that is accessible to your application. For example unzip
instantclient-basic-windows.x64-19.22.0.0.0dbru.zip
toC:\oracle\instantclient_19_22
. - Oracle Instant Client libraries require a Visual Studio redistributable with a 64-bit or 32-bit architecture to match Instant Client’s architecture. Each Instant Client requires a different redistributable version:
- For Oracle Instant Client 21, install Visual Studio 2019 Redistributable or later
- For Oracle Instant Client 19, install Visual Studio 2017 Redistributable
- For Oracle Instant Client 18 and 12.2, install the Visual Studio 2013 Redistributable
- For Oracle Instant Client 12.1, install Visual Studio 2010 Redistributable
- For Oracle Instant Client 11.2, install Visual Studio 2005 Redistributable
You can also find out the version required by locating the library
OCI.DLL
and running:dumpbin /dependents oci.dll
For example, if you see
MSVCR120.dll
then you need the VS 2013 Redistributable. If you seeMSVCR100.dll
then you need the VS 2010 Redistributable. If you seeMSVCR80.dll
then you need the VS 2005 Redistributable.
- Call oracledb.initOracleClient() to enable Thick mode, seeEnabling node-oracledb Thick Mode on Windows.
- If you use the optional Oracle configuration files, seeUsing Optional Oracle Configuration Files.
If disk space is important, most users will be able to use the smaller Basic Light package instead of the Basic package. Review itsglobalization limitations. Disk space can be reduced by removing unnecessary libraries and files from either the Basic or Basic Light packages. The exact libraries depend on the Instant Client version. Refer to the Oracle Database Instant Client documentation.
2.6.3.2. Local Database or Full Client
Follow these steps if you are running Node.js on the same machine where Oracle Database is installed.
Node-oracledb Thick mode applications can use Oracle Client 21, 19, 18, 12, or 11.2 libraries from a local Oracle Database or full Oracle Client (such as installed by Oracle’s GUI installer).
The pre-built node-oracledb binary was built with Visual Studio 2017 and requires the matching redistributable. Ensure that PATH
contains the correct binary directory, for example C:\oracle\product\12.2.0\dbhome_1\ bin
.
For easy development, the free Oracle XE version of the database is available on Windows. Applications developed with XE may be immediately used with other editions of the Oracle Database.
You may need Administrator privileges to set environment variables or install software.
To use node-oracledb in Thick mode with a local database or full client:
- Place the optional Oracle Client configuration files such astnsnames.ora, sqlnet.ora, and oraaccess.xml as detailed in Using Optional Oracle Configuration Files.
- Call oracledb.initOracleClient() in your application to enable Thick mode, see Enabling node-oracledb Thick Mode on Windows.
2.7. Installing node-oracledb Without Internet Access
On a machine with internet access, download the node-oracledb package fromnpm, for example fromhttps://registry.npmjs.com/oracledb/-/oracledb-6.0.0.tgz
Transfer the file to the desired machine and install it, for example with:
npm install your_dir_path/oracledb-6.0.0.tgz
Then follow the node-oracledb installation instructions for your operating system.
Alternatively, on an identical machine that has access to the internet, install node-oracle following the instructions for your operating system. Then copy node_modules/oracledb
to the offline computer. If you are using the Thick mode, then also copy the Oracle Client libraries to the offline computer.
By default, node-oracledb runs in a Thin mode which connects directly to Oracle Database so no further installation steps are required.
To use additional features available in Thick mode, you need Oracle Client libraries installed.
If you are using Thick mode on an architecture that does not have a pre-supplied binary then you can build your own node-oracledb package, seeCreating a node-oracledb package from source code. Consider self-hosting the node-oracledb package inside your network, seeHosting your own node-oracledb Packages.
2.8. Installing node-oracledb from Source Code
Some build tools are required to install node-oracledb from source code.
- Recent Node.js tools should work with Python 3 but you may need to have Python 2.7 for the node-gyp utility.
- Check if you have an old version of
node-gyp
installed. Try updating it. Also, try deleting$HOME/.node-gyp
or equivalent. - If another version of Python occurs first in your binary path then run
npm config set python /wherever/python-2.7/bin/python
or use the--python
option to indicate the correct version. For example:npm install --python=/whereever/python-2.7/bin/python oracledb
. - On Windows, install the Python 2.7 MSI and select the customization option to “Add python.exe to Path”.
- Check if you have an old version of
- If you want to build the optional node-oracledb Thick mode binary, install a C compiler:
- On Linux, GCC 4.8.5 (the default on Oracle Linux 7) is known to work.
- On macOS install Xcode from the Mac App store.
- On Windows, install a C build environment such as Microsoft Visual Studio 2017. Compilers supported by Oracle libraries are found inOracle documentation for each version, for example Oracle Database Client Installation Guide for Microsoft Windows. Some users report that the npm
windows-build-tools
package has the necessary tools to build node-oracledb from source code.
The directories with thepython
andnpm
executables should be in your PATH environment variable. On Windows you can use vcvars64.bat (or vcvars.bat if you building with 32-bit binaries) to set the environment. Alternatively you can open the ‘Developer Command Prompt for Visual Studio’ which has environment variables already configured.
2.8.1. Installing GitHub Clones and ZIP Files
- You can clone the node-oracledb source code repository or download a ZIP from GitHub.
- Either clone the node-oracledb repository using the
git
source code utility:
git clone --recurse-submodules https://github.com/oracle/node-oracledb.git
Then checkout the branch or tag you wish to build:
git checkout main
git submodule update - Alternatively, if you download a node-oracledb ZIP file from GitHub, choose the appropriate tag first.
If you intend to build the optional Thick mode binary module, separately download the ODPI-C submodulecode and extract it into aodpi
subdirectory. Check the version of ODPI-C downloaded matches the version used in the node-oracledb GitHub repository. The version is shown in thedpi.h
header file.
- Either clone the node-oracledb repository using the
- If you only want to use node-oracledb in Thin mode, then delete the file
binding.gyp
. - With the node-oracledb source code in
your_dir_path/node-oracledb
use apackage.json
dependency like:
"dependencies": {
"oracledb": "file:/your_dir_path/node-oracledb"
},
and install:
Alternatively, change to your application directory and run:
npm install your_dir_path/node-oracledb
Note that if this builds the Thick mode binary then you need to make sure the ODPI-C submodule is present, either by using--recurse-submodules
when cloning or by explicity adding it to the extracted ZIP archive. Without ODPI-C, building the binary module will fail with an error like‘dpi.h’ file not found.
2.8.2. Installing using GitHub Branches and Tags
Node-oracledb can be installed directly from GitHub tags and branches. The git
source code utility is required for this method.
To install the current development code from the GitHub main branch, use a package.json
dependency like:
"dependencies": { "oracledb": "oracle/node-oracledb#main" },
Alternatively, use the command:
npm install oracle/node-oracledb#main
To install from a tag, replace main
with the tag name like:oracle/node-oracledb#v6.0.0
.
This will install node-oracledb and build the optional Thick mode binary.
2.8.3. Installing from a Source Package
Users without git
can compile pre-bundled source code using apackage.json
dependency like:
"dependencies": { "oracledb": "https://github.com/oracle/node-oracledb/releases/download/v6.0.0/oracledb-src-6.0.0.tgz" },
Or install with:
npm install https://github.com/oracle/node-oracledb/releases/download/v6.0.0/oracledb-src-6.0.0.tgz
This will install node-oracledb and build the optional Thick mode binary.
2.8.4. Installing from Oracle’s Repository
Oracle has a mirror of the GitHub repository source code that can be cloned with:
git clone --recurse-submodules https://opensource.oracle.com/git/oracle/node-oracledb.git
With the node-oracledb source code in your_dir_path/node-oracledb
use a package.json
dependency like:
"dependencies": { "oracledb": "file:/your_dir_path/node-oracledb" },
Alternatively, change to your application directory and run:
npm install your_dir_path/node-oracledb
This will install node-oracledb and build the optional Thick mode binary.
2.8.5. Creating a node-oracledb Package from Source Code
You can create a package containing the required JavaScript files and optionally also containing the Thick mode binary. This is equivalent to the package that is normally installed from the npm registry.
To create the package, follow the instructions in package/README.
Your new package can be self-hosted for use within your company, or it can be used directly from the file system to install node-oracledb.
2.9. Hosting Your Own node-oracledb Packages
You can host node-oracledb packages locally.
Download the node-oracledb package from npm, for example fromhttps://registry.npmjs.com/oracledb/-/oracledb-6.0.0.tgz. Alternatively, if you want to build your own binaries and node-oracledb package, see Creating a node-oracledb Package from Source Code.
If you make the package accessible on your local web server, for example at www.example.com/oracledb-6.0.0.tgz, then your package.json
would contain:
. . . "dependencies": { "oracledb": "https://www.example.com/oracledb-6.0.0.tgz" }, . . .
Or you would install with:
npm install https://www.example.com/oracledb-6.0.0.tgz
2.10. Using node-oracledb in Docker
Docker allows applications to be containerized. Each application will have a Dockerfile
with steps to create a Docker image. Once created, the image can be shared and run.
Sample Dockerfiles for Oracle Linux are available onGitHub. Some container images are in Oracle’s GitHub Container Registry.
2.10.1. Installing Node.js in Docker
If your Dockerfile
uses Oracle Linux:
Then you can install Node.js fromyum.oracle.comusing:
RUN yum -y install oracle-nodejs-release-el7 &&
yum -y install nodejs &&
rm -rf /var/cache/yum
One alternative to Oracle Linux is to use a Node.js image from Docker Hub, for example using:
Note: You should review Oracle’s supported distributions before choosing an operating system.
2.10.2. Installing node-oracledb and Your Application
Include node-oracledb as a normal dependency in your applicationpackage.json
file:
. . . "scripts": { "start": "node server.js" }, "dependencies": { "oracledb" : "^6" }, . . .
The package.json
and application file can be added to the image, and dependencies installed when the image is built:
WORKDIR /myapp ADD package.json server.js /myapp/ RUN npm install
CMD exec node server.js
2.10.3. Installing Instant Client in Docker
If you want to use node-oracledb in Thick mode, then you need to separately install Oracle Instant Client in the container.
Review the available Instant Client Linux x86_64 packages for Oracle Linux 7and Oracle Linux 8. Older Oracle Instant Clients are in theOracle Linux 7 and Oracle Linux 8repositories.
Packages for Oracle Linux ARM (aarch64) are available for Oracle Linux 8.
Instant Client RPMs and ZIP files are also available from Oracle Database Instant Client download pages.
There are various ways to install Instant Client. Three methods are shown below.
- Using Oracle Linux Instant Client RPMs
If you have an Oracle Linux image:
Then you can install Instant Client RPMs:
RUN yum -y install oracle-instantclient-release-el7 && \
yum -y install oracle-instantclient-basic && \
rm -rf /var/cache/yum - Automatically downloading an Instant Client ZIP file
You can automatically download an Instant Client ZIP file during image creation. This is most useful on Debian-based operating systems. (Note: you should review Oracle’s supported distributions before choosing an operating system).
Thelibaio
(orlibaio1
),wget
andunzip
packages will need to be added manually.
On Oracle Linux:
RUN yum install -y libaio wget unzip
On a Debian-based Linux:
RUN apt-get update && apt-get install -y libaio1 wget unzip
Then, to use the latest available Instant Client:
RUN wget https://download.oracle.com/otn_software/linux/instantclient/instantclient-basiclite-linuxx64.zip && \
unzip instantclient-basiclite-linuxx64.zip && rm -f instantclient-basiclite-linuxx64.zip && \
cd /opt/oracle/instantclient* && rm -f jdbc occi mysql mql1 ipc1 jar uidrvci genezi adrci && \
echo /opt/oracle/instantclient > /etc/ld.so.conf.d/oracle-instantclient.conf && ldconfig
When using Instant Client 19 on recent Linux versions, such as Oracle Linux 8, you may also need to install thelibnsl
package. This is not needed from Instant Client 21 onward. - Copying Instant Client zip files from the host
To avoid the cost of repeated network traffic, you may prefer to download the Instant Client Basic Light zip file to your Docker host, extract it, and remove unnecessary files. The resulting directory can be added during subsequent image creation. For example, with Instant Client Basic Light 21.1, the host computer (where you run Docker) could have a directoryinstantclient_21_1
with these files:
libclntshcore.so.21.1
libclntsh.so.21.1
libnnz21.so
libociicus.so
With this, your Dockerfile could contain:
ADD instantclient_21_1/* /opt/oracle/instantclient_21_1
RUN echo /opt/oracle/instantclient_21_1 > /etc/ld.so.conf.d/oracle-instantclient.conf && \
ldconfig
Thelibaio
orlibaio1
package will be needed.
On Oracle Linux:
RUN yum install -y libaio
On a Debian-based Linux:
RUN apt-get update && apt-get install -y libaio1
When using Instant Client 19 on recent Linux versions, such as Oracle Linux 8, you may also need to install thelibnsl
package. This is not needed from Instant Client 21 onward.
2.10.4. Using Oracle Net configuration Files and Oracle Wallets
Optional Oracle Net Configuration files (liketnsnames.ora
and sqlnet.ora
) and files that need to be secured such asOracle wallets can be mounted at runtime using a Docker volume. When using the optional node-oracledb Thick mode, it is convenient to map the volume to the network/admin
subdirectory of Instant Client so theTNS_ADMIN
environment variable does not need to be set. For example, when the Wallet or configuration files are in /OracleCloud/wallet/
on the host computer, and the image uses Instant Client 19.18 RPMs, then you can mount the files using:
docker run -v /OracleCloud/wallet:/usr/lib/oracle/19.18/client64/lib/network/admin:Z,ro . . .
The Z
option is needed when SELinux is enabled.
2.10.4.1. Example Application in Docker
This example consists of a Dockerfile
, a package.json
file with the application dependencies, a server.js
file that is the application, and an envfile.list
containing the database credentials as environment variables. This example show node-oracledb Thick mode.
If you use Oracle Linux, your Dockerfile
will be like:
FROM oraclelinux:7-slim
RUN yum -y install oracle-instantclient-release-el7 &&
yum -y install oracle-instantclient-basiclite &&
rm -rf /var/cache/yum
WORKDIR /myapp ADD package.json server.js /myapp/ RUN npm install
CMD exec node server.js
An equivalent Dockerfile that uses a Node.js image is:
FROM node:18-buster-slim
RUN apt-get update && apt-get install -y libaio1 wget unzip
WORKDIR /opt/oracle
RUN wget https://download.oracle.com/otn_software/linux/instantclient/instantclient-basiclite-linuxx64.zip &&
unzip instantclient-basiclite-linuxx64.zip && rm -f instantclient-basiclite-linuxx64.zip &&
cd /opt/oracle/instantclient* && rm -f jdbc occi mysql mql1 ipc1 jar uidrvci genezi adrci &&
echo /opt/oracle/instantclient > /etc/ld.so.conf.d/oracle-instantclient.conf && ldconfig
WORKDIR /myapp ADD package.json server.js /myapp/ RUN npm install
CMD exec node server.js
Note: You should review Oracle’s supported distributions before choosing an operating system.
For either Dockerfile, the package.json
is:
{ "name": "test", "version": "1.0.0", "private": true, "description": "Docker Node.js application", "scripts": { "start": "node server.js" }, "keywords": [ "myapp" ], "dependencies": { "oracledb" : "^6" }, "author": "Me", "license": "UPL" }
The application server.js
contains code like:
. . .
connection = await oracledb.getConnection({
user: process.env.NODE_ORACLEDB_USER,
password: process.env.NODE_ORACLEDB_PASSWORD,
connectString: process.env.NODE_ORACLEDB_CONNECTIONSTRING
});
const result = await connection.execute(
SELECT TO_CHAR(CURRENT_DATE, 'DD-Mon-YYYY HH24:MI') AS D FROM DUAL
,
[],
{ outFormat: oracledb.OUT_FORMAT_OBJECT }
);
console.log(result);
. . .
The environment variables in envfile.list
are used at runtime. The file contains:
NODE_ORACLEDB_USER=hr NODE_ORACLEDB_PASSWORD=
NODE_ORACLEDB_CONNECTIONSTRING=server.example.com/orclpdb1
The image can be built:
docker build -t nodedoc .
Alternatively, if you are behind a firewall, you can pass proxies when building:
docker build --build-arg https_proxy=http://myproxy.example.com:80 --build-arg http_proxy=http://www-myproxy.example.com:80 -t nodedoc .
Finaly, a container can be run from the image:
docker run -ti --name nodedoc --env-file envfile.list nodedoc
The output is like:
{ metaData: [ { name: 'D' } ], rows: [ { D: '24-Nov-2019 23:39' } ] }
2.11. Installing Configuration Provider Modules for node-oracledb
To use node-oracledb withcentralized configuration providers, you must install the necessary modules for your preferred configuration provider as detailed below.
2.11.1. Install Modules for Azure App Configuration Provider
For node-oracledb to work with Azure App Configuration Provider, you must install the following Microsoft Azure modules:
- Install the Azure App Configuration module using:
npm install @azure/app-configuration - Install the Azure Identity module using:
npm install @azure/identity
This library offers a variety of credential classes capable of acquiring Microsoft Entra ID (formerly Azure Active Directory) token to authenticate service requests. - Optionally, you need to install the Azure Key Vault module if a password is stored in the Azure Key vault. This can be done using:
npm install @azure/keyvault-secrets
See Azure App Configuration Provider for information on using this configuration provider with node-oracledb.
2.11.2. Install Modules for OCI Object Storage Configuration Provider
For node-oracledb to work with OCI Object Storage configuration provider, you must install the following OCI modules:
- Install the OCI Node.js Client for Common Utilities module using:
- Install the OCI Node.js Client for ObjectStorage Service module using:
npm install oci-objectstorage - Optionally, you need to install the OCI Node.js Client for Secrets Service module if a password is stored in the OCI vault. This can be done by using:
See Managing Vault Secrets for more information.
See OCI Object Storage Configuration Provider for information on using this configuration provider with node-oracledb.
2.12. Installing Cloud Native Authentication Modules for node-oracledb
To use node-oracledb with a Cloud Native Authentication plugin, you must install the necessary modules for your preferred plugin as detailed below.
2.12.1. Install Modules for the OCI Cloud Native Authentication Plugin
For node-oracledb to use the Oracle Cloud Infrastructure (OCI) Cloud Native Authentication plugin, you must install the Node.js SDK for OCI module by using:
See Cloud Native Authentication with the extensionOci Plugin for more information on using the extensionOci
plugin in node-oracledb.
2.12.2. Install Modules for the Azure Cloud Native Authentication Plugin
For node-oracledb to use the Azure Cloud Native Authentication plugin, you must install the Microsoft Authentication Library for Node (msal-node) by using:
npm install @azure/msal-node
See Cloud Native Authentication with the extensionAzure Plugin for more information on using theextensionAzure
plugin in node-oracledb.