Build a Node.js Application

To build a Node.js application that accesses a JSON database, you start by configuring your development system to support database access that can take advantage of the high performance features of Autonomous JSON Database. Then, in your application you code database connections and SQL statements to take advantage of these features.

Configure Your Node.js Development System

To configure your development system so that your Node.js application can take advantage of the high performance features of a JSON database, you perform these steps.

  1. Download and install Node.js.
  2. Download and install Oracle Instant Client.
  3. Download and install node-oracledb.
  4. Download the client credentials for the database and make them available to Oracle Instant Client.

Download and Install Node.js

Download and install Node.js for your system's OS and architecture:

  • Oracle Linux:

    Run these commands to download and install the latest version of Node.js:

    sudo yum install -y oracle-release-el7 oracle-nodejs-release-el7
    sudo yum install -y nodejs 
  • Other OSes and architectures:

    Go to the Node.js Downloads page, select the latest LTS (Long Term Support) version for your system's OS and architecture, and install it.

Download and Install Oracle Instant Client

You need Oracle Instant Client libraries version 19.6 or later.

Download and install the Oracle Instant Client basic package for your system's OS and architecture:

  • Oracle Linux:

    Run these commands to download and install the Oracle Instant Client basic package:

    sudo yum -y install oracle-release-el7
    sudo yum -y install oracle-instantclient19.3-basic

    (If you want to see a list of all Instant Client packages, go to http://yum.oracle.com/repo/OracleLinux/OL7/oracle/instantclient/x86_64/index.html.)

  • Other OSes and architectures:

    1. Go to the Oracle Instant Client Downloads page and select the download for your system's OS and architecture.

    2. On the download page, accept the Oracle Technology Network License Agreement, download the latest version of the Basic Package, and then install it by following the instructions at the bottom of the download page.

Download and Install node-oracledb

Download and install the node-oracledb add-on for Node.js for your system's OS and architecture:

  • Oracle Linux:

    Run these commands to download and install the latest version of node-oracledb:

    sudo yum install -y oracle-release-el7 oracle-nodejs-release-el7
    sudo yum install -y node-oracledb-node10
  • Other OSes and architectures:

    Go to the Installing node-oracledb page, choose the "My database is on another machine" instructions for your OS and architecture, and then follow the Install the add-on instructions.

Download and Install Client Credentials for the Database

  1. Download the zip file containing client credentials for your database to a secure directory on your computer.

    This zip file is available for download from the database's Details page in the Oracle Cloud console. If you have an Oracle Cloud user account that permits you to access this page, download the credentials as follows. If you don't have such an account, you need to get the zip file from the administrator of the database, together with the password that was used to protect the zip file.

    1. In your web browser, sign in to Oracle Cloud and navigate to the Details page for the JSON database.

    2. Click DB Connection.

    3. On the Database Connection page click Download.

    4. In the Download Wallet dialog, enter a wallet password in the Password field and confirm the password in the Confirm Password field.

      The password must be at least 8 characters long and must include at least 1 letter and either 1 numeric character or 1 special character.

    5. Click Download to save the client credentials zip file to a secure directory.

  2. After downloading the zip file, follow these steps:

    1. Unzip the client credentials zip file.

    2. Edit the sqlnet.ora file provided in the client credentials, replacing "?/network/admin" with the full path of the directory where you unzipped the client credentials; for example, change:

      (DIRECTORY="?/network/admin")

      to:

      (DIRECTORY="/users/jdoe/adbcredentials")
    3. Create the TNS_ADMIN environment variable, setting its value to the full path of the directory where you unzipped the client credentials.

Code Database Connections and SQL Statements

Follow these steps to ensure optimal performance of your application's use of the database.

  1. Add the dependency on the node-oracledb add-on to your application's package.json file.

  2. Code connections for high performance.

Add the node-oracledb Dependency to package.json

Edit the dependencies object in the package.json file for your application, adding the oracledb package and version. (Use command npm init to generate package.json if it doesn't exist.) For example:

. . .
"dependencies": {
  . . .,
  "oracledb": "^4.0",
  . . .
},
. . .

For detailed information about the dependencies object, see the npm-package.json page. To display the oracledb version installed, you can use the npm list command; for example:

npm list -g --depth=0

Code Connections for High Performance

To achieve high performance, follow these guidelines when making connections to the database.

  • Use connection pools.
  • Use the predefined database service that best matches the operations you will be performing. For most purposes working with JSON data, this is service tp, the typical application connection service for transaction processing operations. For information about the predefined database services, see Database Service Names for Autonomous Transaction Processing and Autonomous JSON Database in Using Oracle Autonomous Database on Shared Exadata Infrastructure.

For example:

var oracledb = require('oracledb');
var config = {
  user: process.env.NODE_ORACLEDB_USER || "ADMIN",
  password: process.env.NODE_ORACLEDB_PASSWORD,
  connectString : process.env.NODE_ORACLEDB_CONNECTIONSTRING || "mydb_tp",
  poolMin: 10,
  poolMax: 10,
  poolIncrement: 0,
}

async function getCollection() {
  oracledb.autoCommit = true;
  await oracledb.createPool(config);
  var conn = await oracledb.getConnection();
  var soda = conn.getSodaDatabase();
  var collection = await soda.createCollection('myCollection');
conn.close();
}

getCollection();

This example creates a pool for connections to database service tp.

Additional Resources

For detailed information about node-oracledb, go to the node-oracledb Documentation page, which includes both an API Reference and a User Guide.

For code examples that demonstrate a wide variety of node-oracledb features, go to the node-oracledb examples folder.