Connect with Node.js
This section explains how to connect an app using Node.js to your cloud service.
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.
- 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
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.C:\netadmin or /home/myuser/netadmin
-
Edit the unzipped
sqlnet.ora
file and change the wallet location to the unzipped directory.For example, change:
to:WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY=?/network/admin)))
or, on Linux, to:WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="C:\netadmin")))
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 exampleC:\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:
This command can also be added to login files such asexport TNS_ADMIN=/home/myuser/netadmin
$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, usedbaccess
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
toconnection-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
toconnection-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 throughprocess.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 theconnection-test-app
directory created earlier. -
Change directories into the
client_credentials
directory and open thesqlnet.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. Thesqlnet.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.
-
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 namedEECS_PASSWORD
and its value will be the password of the database user specified inEECS_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.