Running node-oracledb – the Oracle Database Driver for Node.js – in the Pre Built VM for Database Development

Node applications may want to have access to databases – similar to access to the file system, external APIs over HTTP and other resources. Just like Java applications use a JDBC driver to access a relational database, Node.js applications can leverage a database driver for the database they want to access. There is no standard for database drivers or for interacting with a relational database. There is no JDBC-like API. Working with different databases is done in different ways.

Oracle has created an open source project – available on GitHub – called node-oracledb. This project provides a Node.js database driver to the Oracle Database. It leverages Oracle Database client libraries – the thick OCI API – that need to be installed on the server running the node application. Through node-oracledb, the interaction from a node application with an Oracle Database becomes fairly easy and straightforward – similar to JDBC but simpler. And asynchronous of course – using callbacks to handle the responses returned from the database. Performing queries, DDL and DML as well as PL/SQL calls is all supported pretty well as are native Oracle data types.

This node-oracledb package can easily be installed, using npm oracledb. However, in order to the module work, we need to go through a few steps. The node module leverages the Oracle Database Client libraries – thick OCI – to connect to a database. The database can be on a completely different server and even run in the cloud. But the database client libraries need to be available on the same machine as where the node.js engine is running. Performing a smooth installation turns out to not always be simple. Two or more Docker container [scripts] are offered from the community, but I could not get them to work. I did not want to have a local database installed – I try to organize my work in VMs and preferably Docker containers.

The easiest way I found to get going with node-oracledb was by using the Pre Built VirtualBox image available from OTN for trying out database development: http://www.oracle.com/technetwork/database/enterprise-edition/databaseappdev-vm-161299.html. This image contains an Oracle Database – and thereby also the required client libraries. It turns out to be fairly easy to add Node.js and the node-oracledb package to this VM and quickly run your first node application that actually talks to the database. Below are steps that worked for me.

a) Download the Virtual Box image from http://www.oracle.com/technetwork/database/enterprise-edition/databaseappdev-vm-161299.html

b) Import the downloaded file – for example DeveloperDaysVM2016-01-22_23.ova – into VirtualBox.

When the import is complete, you can increase the allocated memory – to 4GB for example.

c) Run the imported machine.

When the machine is run, the Oracle Database 12.1.0.2 database instance will automatically be started.

Some details for this database:
Oracle SID : orcl12c

Pluggable DB : orcl

ALL PASSWORDS ARE : oracle

ORACLE_HOME (should be set to): /u01/app/oracle/product/12.1.0.2/db_1

d) Open a Terminal.

start a sudo session:

sudo –s

And perform these installation steps:

curl –silent –location https://rpm.nodesource.com/setup_4.x | bash –

yum -y install nodejs

yum –y install git

Exit the sudo session – and resume as user oracle.

Check if ORACLE_HOME is set (echo $ORACLE_HOME). If it is not set, set it:
export ORACLE_HOME=/u01/app/oracle/product/12.1.0.2/db_1

Now it is time to install node-oracledb. Run:

npm install oracledb

This will do the installation of the Node Oracle Database Driver.

e) To get hold of some hands-on resources inside the VM:

git clone https://github.com/lucasjellema/sig-nodejs-amis-2016

then navigate to /sig-nodejs-amis-2016/part6-oracledb. Run the node program select.js:
node select.js

This will perform a select operation against the HR schema in the local database. You should see a department record being reported on.

Now check the contents of the select.js program.

It shows you quite a bit about how the Oracle Database Driver for Node has you interact with the Oracle database. The connection details are configured in the file dbconfig.js that is required into select.js. This file is currently configured to connect to the HR schema in the local database.

f) Run select_set.js using

node select_set.js

This is an example for retrieving a set of records.

Note: also see examples of using the node oracle database driver at : https://github.com/oracle/node-oracledb/tree/master/examples