Installing node-oracledb Version 2

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.

1. Node-oracledb Overview

The steps below create a Node.js installation for testing. Adjust the
steps for your environment.

This node-oracledb release has been tested with Node 4, 6, 8 and 9 on
64-bit Oracle Linux, Windows and macOS. The add-on can also build on
some 32-bit Linux, 32-bit Windows, Solaris and AIX environments, but
these architectures have not been fully tested.

Node-oracledb is an add-on
available as C++ and 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.

Changes in node-oracledb version 2.0

In node-oracledb version 2.0, pre-built binaries are now available for
some environments.

Building from source code has improved significantly in node-oracledb
version 2.0 The Oracle header files, and the node-oracledb environment
variables OCI_INC_DIR and OCI_LIB_DIR are no longer required.

The Oracle client libraries must now always be in the default library
search path, such as PATH (on Windows), or LD_LIBRARY_PATH (on
Linux), or in ~/lib (on macOS). This is because they are
dynamically loaded during execution. ‘Rpath’ linking is no longer
performed on Linux or macOS.

Any node-oracledb version 2.0 binary will run with any of the Oracle
client 11.2, 12.1 or 12.2 libraries without needing recompilation.
Note the available Oracle functionality will vary with different
Oracle Client and Database versions.

After installation of node-oracledb, your Node.js applications will
be able to connect to your database. The database can be on the
same machine as Node.js, or on a remote machine. Node-oracledb does
not install or create a database.

If pre-built binaries are not available or desired, you need these
additional tools to build from source code:

A compiler.

Use Visual Studio on Windows, GCC on Linux or Xcode on macOS.
When building with Node 4 onward, the compiler must support
C++11. Note the default compiler on Oracle Linux 6 and RHEL 6 does
not have the required support. Install GCC 4.8 or later or
upgrade to Oracle Linux 7.

Python 2.7.

Python 2.7 is needed by node-gyp, which is invoked by npm. Run
python --version to find the version you have.

If another version of Python occurs first in your binary path then,
when you install node-oracledb, 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=/wherever/python-2.7/bin/python oracledb.

3.2.4 Install the free Oracle Instant Client ‘Basic’ RPM

This will install the required libaio package, if it is not already
present.

If you have a ULN subscription, you can alternatively use yum
to install the Basic package after enabling the
ol7_x86_64_instantclient or ol6_x86_64_instantclient channel,
depending on your version of Linux.

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:

If you intend to co-locate optional Oracle configuration files such as
tnsnames.ora, sqlnet.ora, ldap.ora, or
oraaccess.xml with Instant Client, they can be put in a
network/admin subdirectory under lib/. Create this if needed.
For example:

sudo mkdir -p /usr/lib/oracle/12.2/client64/lib/network/admin

This is the default Oracle configuration directory for applications
linked with this Instant Client.

Alternatively, if you use Oracle client configuration files, they can
be put in another, accessible directory. Then set the environment
variable TNS_ADMIN to that directory name.

If you intend to co-locate optional Oracle configuration files such as
tnsnames.ora, sqlnet.ora, ldap.ora, or
oraaccess.xml with Instant Client, they can be put in a
network/admin subdirectory. Create this if needed. For example:

sudo mkdir -p /opt/oracle/instantclient_12_2/network/admin

This is the default Oracle configuration directory for applications
linked with this Instant Client.

Alternatively, if you use Oracle client configuration files, they can
be put in another, accessible directory. Then set the environment
variable TNS_ADMIN to that directory name.

3.2.4 The default Oracle Client configuration directory

Alternatively, if you use Oracle client configuration files, they can
be put in another, accessible directory. Then set the environment
variable TNS_ADMIN to that directory name.

3.4.5 Run an example program

Set required Oracle environment variables, such as ORACLE_HOME and
LD_LIBRARY_PATH by executing:

source /usr/local/bin/oraenv

Or, if you are using Oracle XE, by executing:

source /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh

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.

If you intend to co-locate optional Oracle configuration files such as
tnsnames.ora, sqlnet.ora, ldap.ora, or
oraaccess.xml with Instant Client, they can be put in a
network/admin subdirectory. Create this if needed. For example:

sudo mkdir -p /opt/oracle/instantclient_12_2/network/admin

This is the default Oracle configuration directory for applications
linked with this Instant Client.

Alternatively, if you use Oracle client configuration files, they can
be put in another, accessible directory. Then set the environment
variable TNS_ADMIN to that directory name.

If you intend to co-locate optional Oracle configuration files such as
tnsnames.ora, sqlnet.ora, ldap.ora, or
oraaccess.xml with Instant Client, they can be put in a
C:\oracle\instantclient_12_2\network\admin subdirectory. Create
this if needed.

This is the default Oracle configuration directory for applications
linked with this Instant Client.

Alternatively, if you use Oracle client configuration files, they can
be put in another, accessible directory. Then set the environment
variable TNS_ADMIN to that directory name.

3.6.6 Install the Visual Studio Redistributables

The PATH variable needs to include the appropriate VS Redistributable:

3.8 Copying node-oracledb Binaries on Windows

Node-oracledb binaries can be copied between compatible Windows systems.

After node-oracledb has been built on the source computer, copy the
node_modules\oracledb directory to the destination computer’s
node_module directory.

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 PATH. Note the Oracle client library
versions do not have to be the same on different computers, but
node-oracledb behavior and features may then differ.

If you intend to co-locate optional Oracle configuration files such as
tnsnames.ora, sqlnet.ora, ldap.ora, or
oraaccess.xml with Instant Client, they can be put in a
network/admin subdirectory. Create this if needed. For example:

sudo mkdir -p /opt/oracle/instantclient_12_2/network/admin

This is the default Oracle configuration directory for applications
linked with this Instant Client.

Alternatively, if you use Oracle client configuration files, they can
be put in another, accessible directory. Then set the environment
variable TNS_ADMIN to that directory name.

If you intend to co-locate optional Oracle configuration files such as
tnsnames.ora, sqlnet.ora, ldap.ora, or
oraaccess.xml with Instant Client, they can be put in a
network/admin subdirectory. Create this if needed. For example:

mkdir -p /opt/oracle/instantclient_12_2/network/admin

This is the default Oracle configuration directory for applications
linked with this Instant Client.

Alternatively, if you use Oracle client configuration files, they can
be put in another, accessible directory. Then set the environment
variable TNS_ADMIN to that directory name.

3.11 Node-oracledb Installation from Source Code

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”.

Install a C++11 compatible compiler:

On Linux you need GCC 4.8 (or later) because compiling for Node 4
(or later) requires a C++11 compatible compiler. The default
compiler on Oracle Linux 6 and RHEL 6 does not have the required
C++11 support. Install GCC 4.8 or later or upgrade to Oracle
Linux 7.

The directories with the python and npm 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.

3.11.1 Installing using GitHub branches and tags

Node-oracledb can be installed from GitHub tags and branches. In
general, use the most recent release tag.

The git utility is required for this method.

Build node-oracledb from source code by changing the package specifier
so that npm downloads from GitHub instead of from npmjs.com. For
example, to install the code from the GitHub tag ‘v2.1.2’, add
oracle/node-oracledb#v2.1.2 to your package.json dependencies, or
use the command:

Note it may take some time before compilation begins due to the slow
download of source code from GitHub.

3.11.2 Installing GitHub clones and zip files

If you clone node-oracledb or download a zip from GitHub to build
node-oracledb from source code, 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.

If you download a node-oracledb ZIP file from GitHub, you must
separately download the ODPI-C submodule code and extract it into the
odpi directory.

If you clone the GitHub repository, you need to additionally run:

git submodule init
git submodule update

Then build node-oracledb from source code using the Node-oracledb
Installation Instructions for your operating system.
Substitute the command npm install your-dir-path/node-oracledb when
installing.

3.12 Node-oracledb Installation Without Internet Access

There are several ways to install node-oracledb on computers that do
not have internet access, or have no access to either the npm
registry or github.com.

3.12.1 Installing on an Intermediary Machine

Then copy node_modules/oracledb and Oracle client libraries to the
offline computer. Windows users should see Copying node-oracledb
Binaries on Windows and make sure the correct Visual Studio
Redistributable is also installed.

3.12.2 Manually Extracting Pre-built Binaries

If pre-built node-oracledb binaries are available for your version
of Node.js and operating system, you can install manually:

On a computer that has access to github.com, navigate to a release
on the GitHub Release page.

Download the release’s main node-oracledb package, for example
oracledb-2.1.2.tgz.

For example, when installing node-oracledb 2.1.2 on macOS with
Node.js 8, these commands will show the module version is ‘57’, the
platform is ‘darwin’ and the architecture is ‘x64’. The package to
download is oracledb-v2.1.2-node-v57-darwin-x64.gz

Locate node_modules/oracledb/package/extractpackage.js and use it
to unarchive the binary package, for example:

node extractpackage.js path=oracledb-v2.1.2-node-v57-darwin-x64.gz

Create the subdirectory node_modules/oracledb/build/Release and
move the extracted oracledb.node binary to
node_modules/oracledb/build/Release/oracledb.node

Then copy node_modules/oracledb and Oracle client libraries to the
offline computer. Windows users should see Copying node-oracledb
Binaries on Windows and make sure the correct Visual
Studio Redistributable is also installed.

3.12.3 Installing node-oracledb without GitHub Access

Some companies block access to github.com so npm install oracledb
will fail to download binaries, as will installing source code from
GitHub with npm install oracle/node-oracledb.git#v2.1.2.

There are two suggested methods for installation.

3.12.3.1 Use the oracle.com GitHub mirror

Oracle has a mirror of the GitHub repository source code that can be
cloned with:

6. Troubleshooting Node-oracledb Installation Problems

Did you get an HTTPS 404 failure? A pre-built node-oracledb binary
package is probably not available on
https://github.com/oracle/node-oracledb/releases for your Node.js
version or operatiing system. Change your Node.js version or
compile node-oracledb from source code.

Was there a network connection error? Do you need to set
http_proxy and/or https_proxy?

Use npm install --verbose oracledb. Review your output and logs.
Try to install in a different way. Try some potential solutions.
Before installing on Windows also do set
NODE_ORACLEDB_TRACE_INSTALL=TRUE. On Linux and macOS use export
NODE_ORACLEDB_TRACE_INSTALL=TRUE.

When compiling node-oracledb from source, does your compiler have
C++11 support, e.g. use VS 2015 or GCC 4.8.

When compiling node-oracledb from source, do you have Python 2.7?
Run python --version.

Do you have an old version of node-gyp installed? Try updating
it. Also try deleting $HOME/.node-gyp or equivalent.