Two of my favorite Oracle Cloud services are the Exadata Express Cloud Service (Exadata Express) and the Application Container Cloud Service (ACCS). Exadata Express is a fully managed Oracle Database service at an entry-level price point for small to medium sized data and ACCS is an easy way to deploy apps in Docker containers. In this post, I’ll demonstrate how to connect these two services at the most basic level.
What do I mean by “the most basic level”? First, I’m not going to demonstrate how to create an Oracle Cloud account with these two services – I’ll assume you’ve already done that. Also, the demo app in this post will be minimalistic. Normally, I might use the Developer Cloud Service to create a Git repo with an automated build process – not here. This post will focus only on what’s needed to get these two services connected.
Contents:
- Create test app
- Add client credentails
- Deploy app
- Add environment variables
Create test app
Create a new directory named connection-test-app and add the following two files.
{
"runtime":{
"majorVersion":"6"
},
"command": "node index.js",
"release": {},
"notes": ""
}
ACCS apps often have one or two metadata files. In this case, the manifest.json is used to specify the version of Node.js to run and the command to use to start the application.
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);
The index.js contains logic that runs a connection test (lines 6-26) and uses a simple web server to let us know the results of the test (lines 28-39). Note that three environment variables are referenced via process.env. PORT is defined by ACCS, but the other environment variables will be created in the last step of this tutorial.
Add client credentails
To connect to Exadata Express, you must first download the client credentials. Open a browser and sign into your Oracle Cloud account. Then go to the Exadata Express service console, select the service instance that you’d like to connect to, and then click the link to download the client credentials.
Before the client credentials download, you will be prompted to enter a password. You’ll need the password when connecting to Exadata Express using a Java keystore (e.g. with SQL Developer), but not when connecting to the database with OCI (e.g. with node-oracledb).
Enter and confirm the password, then click Download. A file named client_credentials.zip will be downloaded to your machine. 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. The contents of that directory should appear as follows:
Change directories into the client_credentials directory and open the sqlnet.ora file in a text editor. Change the value of DIRECTORY from ?/network/admin to /u01/app/client_credentials. Note that when deploying an app to ACCS, the app’s files are copied to the /u01/app directory of the container. The sqlnet.ora file must point to the location of the client credentails, which can differ depending on the environment.
Deploy app
At this point, we can deploy the app to ACCS. Change directories back up to connection-test-app and compress the contents (not the directory itself) in a new zip file named Archive.zip.
Return to the browser and navigate to the ACCS service console. Click the Create Application button.
Select Node as the application platform.
Set the application name to eecstest, use the Archive file picker to select the application archive created in the previous step, and then set the Instances and Memory options to 1. Click Create to start the deployment process.
The app will appear in the list of ACCS applications where you can obtain its URL.
If you navigate to that URL in a browser, you’ll see that the test has failed – this is expected.
Just one last step to get everything working…
Add environment variables
Return to the ACCS service console and drill into the eecstest app. Select the Deployments option on the left and click the Add button under Environment Variables.
Set Name to TNS_ADMIN and Value to $APP_HOME/client_credentails, then click Save.
Repeat the previous steps to create two more environment variables. The first will be named EECS_USER and its value will be the username of the 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.
After creating the three environment variables, scroll to the top and click the Apply Edits button. This will redeploy the application with the new settings.
After the app is deployed, you can navigate to its URL where you should see that the connection test has succeeded.
As you can see, connecting these two services isn’t difficult once you know what the moving pieces are. When working with a real app, I recommend keeping the client credentials separate from the application files.
If developing locally, the TNS_ADMIN environment variable can point to a local copy of the client credentials used for dev. When deploying to another environment in ACCS, you can use a Developer Cloud Service build process to download the correct client credentials from the Storage Service and add them to the app files before deploying them to ACCS.