Connect with Node.js

This section explains how to connect an app using Node.js to your cloud service.

Topics:

Connect an App with Node.js

Node.js is an open source, cross-platform runtime environment for writing mid-tier and networking applications in JavaScript. This Oracle Database driver can be used to connect to Oracle Database Exadata Express Cloud Service using Instant Client 12.1 with security enforced by using an Oracle Wallet.

In order to connect with Node.js, you need to:

Download and install Instant Client – see Oracle Instant Client
Enable SQL*Net for your service – see Enable Oracle Net Services (SQL*Net) Access for Client Applications
Download client credentials – see Download Client Credentials
Install node-oracledb for Node.js database driver – see Installing node-oracledb

For additional resources, see Node.js Developer Center on the Oracle Technology Network (OTN).

Enable Oracle Network Connectivity and Download the Client Wallet:

If Client Access is not already enabled, follow steps outlined in Enable Oracle Net Services (SQL*Net) Access for Client Applications.
If not already downloaded, follow steps in Download Client Credentials to download security credentials and network configuration files that allow client access to your Exadata Express database.
Unzip the client credentials and move the contents to a directory. For example move the files to
```
C:\netadmin or /home/myuser/netadmin
```
Secure the files so that only users who are authorized to connect to your Exadata Express service have access to them. By default, Oracle recommends granting permissions only to the owner of the files.

Edit the unzipped sqlnet.ora file and change the wallet location to the unzipped directory.

For example, change:

WALLET_LOCATION = (SOURCE = (METHOD = file)
        (METHOD_DATA = (DIRECTORY=?/network/admin)))

to:

WALLET_LOCATION = (SOURCE = (METHOD = file)
        (METHOD_DATA = (DIRECTORY="C:\netadmin")))

or, on Linux, to:

WALLET_LOCATION = (SOURCE = (METHOD = file)
        (METHOD_DATA = (DIRECTORY="/home/myuser/netadmin")))

On Windows, create a new user variable TNS_ADMIN in the Environment Variables pane and set it to the directory containing the unzipped files, for example C:\netadmin. On Windows 8 this pane can be accessed by navigating to Control Panel>System>Advanced System Settings>Environment Variables.
On non-Windows platforms, set the TNS_ADMIN environment variable to the directory with the unzipped files.
For example, in the shell you intend to run your application in, execute:
```
export TNS_ADMIN=/home/myuser/netadmin
```
This command can also be added to login files such as $HOME/.bashrc

Install Node.js Database Driver

Install node-oracledb for Node.js using the updated Instant Client. The steps for installing node-oracledb for Node.js are specific to your platform and environment. For installation steps for various platforms and environments, see the Installing node-oracledb manual.
For additional user documentation, see Documentation for the Oracle Database Node.js Add-on.

Run Your Applications

Update your application to use the Oracle Network Service name given in the unzipped tnsnames.ora file. For example, use dbaccess as the connect string.

Alternatively, change the connect string in tnsnames.ora to match the string used by your application.
Review Known Issues for Oracle Database Exadata Express Cloud Service
Run your application.

Connect with Node.js in ACCS

Node.js is an open source, cross-platform runtime environment for writing mid-tier and networking applications in JavaScript. Oracle Application Container Cloud Service (ACCS) makes it easy to deploy container-based applications in on a variety of platforms, including Node.js.

The following steps demonstrate how to connect Exadata Express from ACCS.

Pre-requisites

You must have an Oracle Cloud account with Exadata Express and ACCS.

Create a Test Application

In this step, you will create a Node.js application to be deployed to ACCS. The application will run a basic connection test and use a simple web server to report the results of the test.

Create a new directory named connection-test-app.
Add a file named manifest.json to connection-test-app with the following contents:
```
{
  "runtime":{
    "majorVersion":"6"
  },
  "command": "node index.js",
  "release": {},
  "notes": ""
}
```
ACCS applications often have one or two metadata files. In this case, the manifest.json specifies the version of Node.js to run and the command that will be used to start the application.

Add a file named index.js to connection-test-app with the following contents:


const http = require('http');
const oracledb = require('oracledb');
let error;
let user;
 
oracledb.getConnection(
    {
      user: process.env.EECS_USER, 
      password: process.env.EECS_PASSWORD,
      connectString: 'dbaccess'
    }, 
    function(err, connection) {
      if (err) {error = err; return;}
      
      connection.execute('select user from dual', [], function(err, result) {
        if (err) {error = err; return;}
 
        user = result.rows[0][0];
        error = null;
 
        connection.close(function(err) {
          if (err) {console.log(err);}
        });
      })
    }
);
 
http.createServer(function(request, response) {
  response.writeHead(200, {'Content-Type': 'text/plain'});
 
  if (error === null) {
    response.end('Connection test succeeded. You connected to Exadata Express as ' + user + '!');
  } else if (error instanceof Error) {
    response.write('Connection test failed. Check the settings and redeploy app!\n');
    response.end(error.message);
  } else {
    response.end('Connection test pending. Refresh after a few seconds...');
  }
}).listen(process.env.PORT);

Note:

Three environment variables are referenced through process.env. PORT is defined by ACCS, but the other environment variables will be created in the last step of this procedure.

Add Client Credentials

In this step, you will download the client credentials to connect to Exadata Express and place them with the application files.

Download the client credentials to connect to Exadata Express database. See Download Client Credentials. Once downloaded, you must treat the files securely to prevent unauthorized database access.
Extract the contents of the client_credentials.zip file to the connection-test-app directory created earlier.
Change directories into the client_credentials directory and open the sqlnet.ora file in a text editor. sqlnet.ora file and change the value of the directory from:
```
?/network/admin
```
to
```
/u01/app/client_credentials.
```
With ACCS, application files are copied to /u01/app/ directory of the container. The sqlnet.ora file must point to the location of the client credentials, which can differ depending on the environment.

Deploy the Application

At this point the application can be deployed to ACCS.

To deploy the application to ACCS, change the directories back up to extracted directory and compress the contents in a new zip file.
Return to the browser and navigate to the ACCS service console. Click Create Application.
Select Node as the application platform.
Provide an application name.
Use the Archive file picker to select the application archive created earlier.

Description of the illustration accs-app-properties.png
Set Instances and Memory (GB): to 1.
Click Create to start the deployment. The application appears in the list of ACCS applications where you can obtain the URL. Navigating to the URL at this point will show the test has failed, this is expected.

Description of the illustration accs_app_created_url.png
Return to the ACCS service console and expand the application you just added.
Click Deployments on the left navigation and click Add under Environmental Variables.

Description of the illustration accs_service_bindings.png
Set Name to TNS_ADMIN and Value as $APP_HOME/client_credentials and click Save.

Note:

If you are developing locally, the TNS_ADMIN environment variable can point to a local copy of the client credentials used for development.
Repeat Step 10 to create two more environmental variables. The first will be named as EECS_USER and its value will be the username of Exadata Express database user you want to connect with. The last environment variable will be named EECS_PASSWORD and its value will be the password of the database user specified in EECS_USER.
Deploy these settings by clicking Apply Edits. When the application finishes deploying, you can navigate to its URL again and you will see that the connection test has succeeded.