Node oracledb installation instructions https oracle github io node oracledb install html
Installing node-oracledb Version 5.5.0Copyright (c) 2015, 2022, Oracle and/or its affiliates. Show
You may not use the identified files except in compliance with the Apache License, Version 2.0 (the “License.”) You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Contents
1. Node-oracledb OverviewThe node-oracledb add-on for Node.js powers high performance Oracle Database applications. The architecture is shown in Node-oracledb Architecture. The steps below create a Node.js installation with node-oracledb. Adjust the steps for your environment. This node-oracledb release has been tested with Node.js 14, 16 and 18 on Oracle Linux x86_64 (releases 7 and 8), Windows, and macOS (Intel x86). The add-on may also build on Linux ARM (aarch64), Windows 32-bit, Solaris and AIX environments, but these architectures have not been tested. This version of node-oracledb may work with older Node.js versions if they are Node-API version 4 compatible. Older versions of node-oracledb may also work with older versions of Node.js. Node-oracledb requires Oracle Client libraries version 11.2 or later, and can connect to Oracle Database 9.2 or later, depending on the Oracle Client library version. Node-oracledb is an add-on available as C source code. Pre-built binaries are available as a convenience for common architectures. Note the operating systems and versions of Node.js that the pre-built 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. 2. Quick Start node-oracledb InstallationSimple installation instructions for Windows, macOS (Intel x86) and Linux (x86_64) are available:
Alternatively, follow these instructions:
See Troubleshooting Node-oracledb Installation Problems if you have installation issues. After installation, learn how to use node-oracledb from the examples and the documentation. 3. Node-oracledb Installation InstructionsInstructions may need to be adjusted for your platform, environment and versions being used.
3.1 PrerequisitesAll installations need:
Pre-built node-oracledb binaries are available for Windows 64-bit, Linux x86_64, and macOS (Intel x86). For other platforms you need to build from source code. 3.2 Node-oracledb Installation on LinuxFor Linux x86_64:
For Linux ARM:
3.2.1 Node-oracledb Installation on Linux x86_64 with Instant Client ZIP filesFollow these steps if your database is on a remote machine and either:
Questions and issues can be posted as GitHub Issues. 3.2.1.1 Install PrerequisitesReview the generic prerequisites. Pre-built binaries were built on Oracle Linux 6 and will require a compatible glibc. The pre-built binaries are known to be usable on Oracle Linux 6, 7, and 8. 3.2.1.2 Install Node.jsDownload and extract the Node.js “Linux Binaries” package. For example, if you downloaded version 14.17.0 for 64-bit you could install Node.js into
Set
3.2.1.3 Install node-oracledbIf you are behind a firewall you may need to set your proxy, for example:
Install
node-oracledb using the If a pre-built node-oracledb binary is not installable or depends on an newer glibc version, uninstall node-oracledb and build the binary from source code, see Node-oracledb Installation from Source Code. 3.2.1.4 Install the free Oracle Instant Client ‘Basic’ ZIP fileDownload the free Basic ZIP file from Oracle Technology Network and unzip it into a directory accessible to your application, for example:
You will need the operating system 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 unzipped to
Alternatively, every shell running Node.js will need to have the link path set:
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:
Refer to the Oracle Instant Client documentation for details. 3.2.1.5 Optionally create the Oracle Client configuration file directoryIf you use optional Oracle configuration files such as
Or you can set the environment variable Another alternative is to put the files in the 3.2.1.6 Run an example programDownload the examples from GitHub. Edit
Run one of the examples, such as Note: Remember to set 3.2.2 Node-oracledb installation on Linux x86_64 with a Local Database or Full ClientQuestions and issues can be posted as GitHub Issues. 3.2.2.1 Install PrerequisitesReview the generic prerequisites. The For easy development, the free Oracle XE version of the database is available on Linux. Applications developed with XE may be immediately used with other editions of the Oracle Database. 3.2.2.2 Install Node.jsDownload and extract the Node.js “Linux
Binaries” package. For example, if you downloaded version 14.17.0 for 64-bit you could install Node.js into
Set
3.2.2.3 Install node-oracledbIf you are behind a firewall you may need to set your proxy, for example:
Install node-oracledb using the If a pre-built binary is successfully installed but isn’t usable because it depends on a different glibc version, uninstall node-oracledb and install again from source code. If a pre-built node-oracledb binary is not installable, the binary can be built from source code, see Node-oracledb Installation from Source Code. 3.2.2.4 The default Oracle Client configuration directoryOptional Oracle client configuration files such as Alternatively, if you use Oracle client configuration files, they can be put in another, accessible directory. Then use 3.2.2.5 Run an example programSet required Oracle environment variables, such as
Or, if you are using Oracle XE 11.2, by executing:
Make sure the Node.js process has directory and file access permissions for the Oracle libraries and other files. Typically the home directory of the Oracle software owner will need permissions relaxed. Download the examples from GitHub. Edit
Run one of the examples, such as 3.2.3 Node-oracledb Installation on Linux x86_64 with Instant Client RPMsFollow 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. Questions and issues can be posted as GitHub Issues. 3.2.3.1 Install PrerequisitesReview the generic prerequisites. Pre-built binaries were built on Oracle Linux 6 and will require a compatible glibc. The pre-built binaries are known to be usable on Oracle Linux 6, 7, and 8. 3.2.3.2 Install Node.jsDownload and extract the Node.js “Linux Binaries” package. For example, if you downloaded version 14.17.0 for 64-bit you could install Node.js into
Set
3.2.3.3 Install node-oracledbIf you are behind a firewall you may need to set your proxy, for example:
Install node-oracledb using the The pre-built binaries were built on Oracle Linux 6. If a pre-built node-oracledb binary is not installable or depends on an newer glibc version, uninstall node-oracledb and build the binary from source code, see Node-oracledb Installation from Source Code. 3.2.3.4 Install the free Oracle Instant Client ‘Basic’ RPMDownload the latest version of the free Basic RPM from yum.oracle.com. Instant Client is available for Oracle Linux 7 and Oracle Linux 8. Older Oracle Instant Clients are also available in the Oracle Linux 6, Oracle Linux 7 and Oracle Linux 8 repositories. The RPMs are also available from Oracle Technology Network. Install Instant Client Basic with sudo or as the root user. You can install directly from yum.oracle.com, for example using:
Alternatively you can manually download the RPM and install from your local file system:
The link instantclient-basic-linuxx64.zip will download the latest version available from OTN. If you have a ULN subscription, another alternative is to use Using any of these methods will install the required 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:
Alternatively, for version 18 and earlier, every shell running Node.js will need to have the link path set:
3.2.3.5 Optionally create the Oracle Client configuration file directoryIf you use optional Oracle configuration files such as
Or you can set the environment variable Another alternative is to
put the files in the 3.2.3.6 Run an example programDownload the examples from GitHub. Edit
Run one of the examples, such as Note: Remember to set 3.2.4 Node-oracledb Installation on Linux ARM (aarch64)A pre-built node-oracledb binary is not available for Linux ARM (aarch64). You need to compile node-oracledb from source code. Oracle Instant Client for Linux ARM (aarch64) can be downloaded from oracle.com. A link to installation instructions is on that page. The various node-oracledb installation sections for Linux x86_64 will give some useful background. 3.2.5 Installing Node.js and node-oracledb RPMs from yum.oracle.comNode.js and node-oracledb Linux RPM packages are available on yum.oracle.com. See Node.js for Oracle Linux for installation details. 3.3 Node-oracledb Installation on Apple macOS (Intel x86)Questions and issues can be posted as GitHub Issues. 3.3.1 Install PrerequisitesReview the generic prerequisites. The pre-built binaries were built on macOS (Intel x86) Big Sur 11.6 Oracle Instant Client libraries are required on macOS. There is no native Oracle Database for macOS but one can easily be run in a Linux virtual machine using Vagrant. See the Oracle Database Vagrant projects. 3.3.2 Install Node.jsDownload the Node.js package for macOS 64-bit and install it. 3.3.3 Install node-oracledbIf you are behind a firewall you may need to set your proxy, for example:
Install node-oracledb using the 3.3.4 Install the free Oracle Instant Client ‘Basic’ packageDownload the Basic 64-bit DMG from Oracle Technology Network. Manual InstallationIn Finder, double click on the DMG to mount it. Open a terminal window and run the install script in the mounted package, for example:
This copies the contents to In Finder, eject the mounted Instant Client package. If you have multiple Instant Client DMG packages mounted, you only need to run Scripted InstallationInstant Client installation can alternatively be scripted, for example:
The Instant Client directory will be Configure Instant ClientThere are several alternative ways to tell node-oracledb where your Oracle Client libraries are, see Initializing Node-oracledb:
3.3.5 Optionally create the Oracle Client configuration file directoryIf you use optional Oracle configuration files such as
Or you can set the environment variable Another alternative is to
put the files in the 3.3.6 Run an example programDownload the examples from GitHub. Edit
Make sure Instant Client is configured as shown above. For example you may want to add calls to Run one of the examples, such as 3.4 Node-oracledb Installation on Microsoft WindowsThere are two ways to install node-oracledb on Microsoft Windows:
3.4.1 Node-oracledb Installation on Microsoft Windows with Instant Client ZIP filesFollow 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. Questions and issues can be posted as GitHub Issues. 3.4.1.1 Install PrerequisitesReview the generic prerequisites. 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. 3.4.1.2 Install Node.jsInstall the 64-bit Node.js MSI (e.g. node-v14.17.0-x64.msi) from nodejs.org. Make sure the option to add the Node and npm directories to the path is selected. 3.4.1.3 Install node-oracledbOpen a terminal window. If you are behind a firewall you may need to set your proxy, for example:
Install node-oracledb using the If a pre-built node-oracledb binary is not installable, the binary can be built from source code, see Node-oracledb Installation from Source Code. 3.4.1.4 Install the free Oracle Instant Client ZIPDownload the free 64-bit Instant Client Basic ZIP file from Oracle Technology Network. If your Node.js architecture is 32-bit, then use the 32-bit Instant Client instead. Windows 7 users: Note that Oracle 19 is not supported on Windows 7. Unzip the ZIP file into a directory that is accessible to your
application. For example unzip ` instantclient-basic-windows.x64-19.11.0.0.0dbru.zip There are several alternative ways to tell node-oracledb where your Oracle Client libraries are, see Initializing Node-oracledb:
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. Refer to the Instant Client documentation. 3.4.1.5 Optionally create the Oracle Client configuration file directoryIf you use optional Oracle configuration files such as
If you use backslashes in the Or you can set the environment variable Another alternative is to put the files in the 3.4.1.6 Install the Visual Studio RedistributablesThe
You can also find out the version required by locating the library
For example, if you see 3.4.1.7 Run an example programDownload the examples from GitHub. Edit
Make sure Instant Client is configured as shown above. For example you may want to
add calls to Run one of the examples, such as 3.4.2 Node-oracledb Installation on Microsoft Windows with a Local Database or Full ClientQuestions and issues can be posted as GitHub Issues. 3.4.2.1 Install PrerequisitesReview the generic prerequisites. The pre-built binaries were built with Visual Studio 2017 and require the matching redistributable. The Oracle software can be either a database home or a full Oracle client installation. Make sure that 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. 3.4.2.2 Install Node.jsInstall the 64-bit Node.js MSI (e.g. node-v14.17.0-x64.msi) from nodejs.org. Make sure the option to add the Node and npm directories to the path is selected. 3.4.2.3 Install node-oracledbOpen a terminal window. If you are behind a firewall you may need to set your proxy, for example:
Install node-oracledb using the If a pre-built node-oracledb binary is not installable, the binary can be built from source code, see Node-oracledb Installation from Source Code. 3.4.2.4 The default Oracle Client configuration directoryOptional Oracle client configuration files such as Alternatively, if you use Oracle client configuration files, they can be put in another, accessible directory. For example in 3.4.2.5 Run an example programDownload the examples from GitHub. Edit
Run one of the examples, such as 3.5 Node-oracledb Installation on AIX on Power Systems with Instant Client ZIP filesQuestions and issues can be posted as GitHub Issues. 3.5.1 Install PrerequisitesReview the generic prerequisites. The GCC compiler is needed. Use GNU Make 4.1-1 or above. Python 2.7 is needed by node-gyp. 3.5.2 Install Node.jsDownload Node.js for AIX on Power Systems. For example, if you downloaded version 10.16.0 you could install Node.js into
Set
3.5.3 Install node-oracledbIf you are behind a firewall you may need to set your proxy, for example:
Set the compiler to GCC: Locate the GitHub tag of the desired node-oracledb version, for example If you have the
Otherwise install using:
3.5.4 Install the free Oracle Instant Client ‘Basic’ ZIP fileDownload the Basic ZIP file from Oracle Technology Network and extract it into a directory that is accessible to your
application, for example
To run applications, you will need to set the link path:
3.5.5 Optionally create the Oracle Client configuration file directoryIf you use optional Oracle configuration files such as
Or you can set the environment variable Another alternative is to put the files in the 3.5.6 Run an example programDownload the examples from GitHub. Edit
Run one of the examples, such as 3.6 Node-oracledb Installation on Oracle Solaris x86-64 (64-Bit) with Instant Client ZIP filesQuestions and issues can be posted as GitHub Issues. 3.6.1 Install PrerequisitesReview the generic prerequisites. 3.6.2 Install Node.jsDownload the Node.js source code. Compile and build the Node.js engine into a directory of your choice, such as
Note: if warnings are shown for Set
3.6.3 Install node-oracledbIf you are behind a firewall you may need to set your proxy, for example:
Use the GNU Locate the GitHub tag of the desired node-oracledb version, for example If you have the
Otherwise install using:
If this fails due to an invalid 3.6.4 Install the free Oracle Instant Client ‘Basic’ ZIP fileDownload the Basic ZIP file from Oracle Technology Network and extract it into a directory that is accessible to your application, for example
To run applications, you will need to set the link path:
3.6.5 Optionally create the Oracle Client configuration file directoryIf you use optional Oracle configuration files such as
Or you can set the environment variable Another
alternative is to put the files in the 3.6.6 Run an example programDownload the examples from GitHub. Edit
Run one of the examples, such as 3.7 Node-oracledb Installation from Source CodeSome build tools are required to compile node-oracledb. Recent Node.js tools should work with Python 3 but you may need to install Python 2.7 for the node-gyp utility.
Install a C compiler:
The directories with the 3.7.1 Installing GitHub clones and ZIP filesIf you clone the node-oracledb repository, or download a zip from GitHub to build node-oracledb from source code, then you need to make sure the ODPI-C submodule is also included. Otherwise the build will fail with an error like ‘dpi.h’ file not found.
With the node-oracledb source
code in
Alternatively change to your application directory and run:
3.7.2 Installing using GitHub branches and tagsNode-oracledb can be installed directly from GitHub tags and branches. The To install the current development code from the GitHub main branch,
use a
Alternatively, use the command:
To install from a tag, replace 3.7.3 Installing from a source packageUsers without
Or install with:
3.7.4 Installing from Oracle’s repositoryOracle has a mirror of the GitHub repository source code that can be cloned with:
With the node-oracledb source code in
Alternatively change to your application directory and run:
3.7.5 Creating a node-oracledb package from source codeYou can create a package containing the binary module and required JavaScript files. This is equivalent to the package that is normally installed from the npm registry. 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.
This package can be shared or self-hosted, see Hosting your own node-oracledb Packages. 3.8 Node-oracledb Installation Without Internet AccessOn a machine with access, download the node-oracledb package from npm, for example from This can be transferred to the desired machine and installed, for example with:
If you are using an architecture that does not have pre-supplied binaries then you can build your own package, see Creating a node-oracledb package from source code. Consider self-hosting the node-oracledb package inside your network, see Hosting your own node-oracledb Packages. Alternatively, on an identical machine that has access to the internet, install node-oracle following the Node-oracledb Installation Instructions for that operating system. Then copy 3.8.1 Copying node-oracledb Binaries on WindowsNode-oracledb binaries can be copied between compatible Windows systems. After node-oracledb has been built or installed on the source computer, copy the Both computers must have the same version and architecture (32-bit or 64-bit) of Node.js. Oracle client libraries of the same
architecture as Node.js should be in the destination computer’s The destination computer’s You can also find out the Redistributable required by locating the library
If you see 3.9 Hosting your own node-oracledb PackagesYou can host node-oracledb packages locally. Download the node-oracledb package from npm, for example from If you make the package accessible on your local web server, for example at www.example.com/oracledb-5.5.0.tgz, then your
Or you would install with:
3.10 Using node-oracledb in DockerDocker allows applications to be containerized. Each application will have a Sample Dockerfiles for Oracle Linux are available on GitHub. Some container images are in Oracle’s GitHub Container Registry. Installing Node.js in DockerIf your Then you can install Node.js from yum.oracle.com using:
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. Installing Instant Client in DockerReview the available Instant Client packages for Oracle Linux 7 and Oracle Linux 8. Older Oracle Instant Clients are also available in the Oracle Linux 7 and Oracle Linux 8 repositories. The RPMs and ZIP files are also available from Oracle Technology Network. There are various ways to install Instant Client. Three methods are shown below.
Installing node-oracledb and your applicationInclude
node-oracledb as a normal dependency in your application
The
Using Oracle Net configuration files and Oracle WalletsOptional Oracle Net Configuration files (like
The Example Application in DockerThis example consists of a If you use Oracle Linux, your
An equivalent Dockerfile that uses a Node.js image is:
Note: you should review Oracle’s supported distributions before choosing an operating system. For either Dockerfile, the
The application
The environment variables in
The image can be built:
Alternatively, if you are behind a firewall, you can pass proxies when building:
Finaly, a container can be run from the image:
The output is like:
4. Installing Older Versions of Node-oracledbPre-built node-oracledb 3 and 4 binaries are available for some platforms and Node.js versions. Review the release tags for availability. You can compile the add-on for other platforms or versions. The node-oracledb 4.2 installation steps are in the version 4.2 INSTALL guide. The node-oracledb 3.1 installation steps are in the version 3.1 INSTALL guide. To get an old add-on you must explicitly use its version when installing, for example:
or your
5. Troubleshooting Node-oracledb Installation ProblemsRead the Node-oracledb Installation Instructions. Google anything that looks like an error. If
If creating a connection fails:
Issues and questions about node-oracledb can be posted on GitHub or Slack (link to join Slack). |