This guide describes how to install, configure, and use the Oracle NoSQL Database Node.js SDK with On-Premise Oracle NoSQL Database.
The SDK requires:
You can install the SDK from the npm registry, or alternatively from GitHub.
You may install Node.js SDK from npm registry
either as a dependency of your project:
npm install oracle-nosqldb --save
or globally:
sudo npm install -g oracle-nosqldb
To install from GitHub:
npm install oracle-nosqldb-5.x.x.tgz --save
or globally:
sudo npm install -g oracle-nosqldb-5.x.x.tgz
To use the SDK with the On-Premise Oracle NoSQL Database you need the following components:
A Oracle NoSQL Database instance may be configured and run in secure or non-secure mode. Secure mode is recommended. See Oracle NoSQL Database Security Guide on security concepts and configuration. Correspondingly, the proxy can be configured and used with secure kvstore or non-secure kvstore.
Your application will connect and use a running NoSQL database via the proxy service. The following sections describe information required in non-secure and secure modes.
In non-secure mode, the driver communicates with the proxy via the HTTP protocol. The only information required is the communication endpoint. For on-premise NoSQL Database, the endpoint specifies the url of the proxy, in the form http://proxy_host:proxy_http_port. For example:
const endpoint = 'http://localhost:8080';
You may also omit the protocol portion:
const endpoint = 'myhost:8080'
See endpoint for details.
In secure mode, the driver communicates with the proxy via HTTPS protocol. The following information is required:
const endpoint = 'https://localhost:8181';
Note that unless using port 443, the protocol portion of the url is required. See endpoint for details.
sql-> CREATE USER <driver_user> IDENTIFIED BY "<driver_password>"
sql-> GRANT READWRITE TO USER <driver_user>
where, the driver_user is the username and driver_password is the password for the driver_user user. In this example, the user driver_user is granted READWRITE role, which allows the application to perform only read and write operations. See Configuring Authentication on how to create and modify users. See Configuring Authorization on how to assign roles and privileges to users.
You can use Oracle NoSQL Database Shell to connect to secure kvstore in order to create the user. For example:
java -jar lib/sql.jar -helper-hosts localhost:5000 -store kvstore -security kvroot/security/user.security
sql-> CREATE USER John IDENTIFIED BY "JohnDriver@@123"
sql-> GRANT READWRITE TO USER John
(The password shown above is for example purpose only. All user passwords should follow the password security policies. See Password Complexity Policies)
The driver requires user name and password created above to authenticate with a secure store via the proxy.
To provide the certificate or certificate chain to the driver, before running your application, set environment variable NODE_EXTRA_CA_CERTS. For example:
export NODE_EXTRA_CA_CERTS="path/to/driver.trust"
node your_application.js
where driver.trust is either a certificate chain file (certificates.pem) for your CA, your root CA's certificate (rootCA.crt) or a self-signed certificate (certificate.pem).
On the other hand, if the certificate chain for your proxy certificate has one of well-known CAs at its root (see above), this step is not required.
The first step in your Oracle NoSQL Database application is to create an instance of NoSQLClient class which is the main point of access to the service. To create NoSQLClient instance, you need to supply a Config object containing information needed to access the service. Alternatively, you may choose to supply a path to JSON file that contains the same configuration information as in Config.
Importing NoSQLClient class and other classes/types from the SDK is done differently depending on whether you are using TypeScript or JavaScript with ES6 modules, or if you are using JavaScript with CommonJS modules:
TypeScript or JavaScript with ES6 modules:
import { NoSQLClient } from 'oracle-nosqldb';
JavaScript with CommonJS modules:
const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
We will use TypeScript/ES6 imports in the tutorial, but both types of imports are supported. For more information, see TypeScript Modules and Node.js ECMAScript Modules.
Since NoSQL Node.js driver is used both for Oracle NoSQL Cloud Service and On-Premise Oracle NoSQL Database, the Config object can specify that we are connecting to on-premise NoSQL Database by setting serviceType property to KVSTORE. You can always explicitly specify serviceType property, but in some cases such as when connecting to secure store and the configuration has auth object that contains kvstore property, the service type will be deduced by the driver. See ServiceType for details.
Other required information has been described in previous sections and is different for connections to non-secure and secure stores.
To connect to the proxy in non-secure mode, you need to specify communication endpoint.
For example, if using configuration JavaScript object:
import { NoSQLClient, ServiceType } from 'oracle-nosqldb';
const client = new NoSQLClient({
serviceType: ServiceType.KVSTORE,
endpoint: 'myhost:8080'
});
You may also choose to store the same configuration in a file. Create file config.json with following contents:
{
"serviceType": "KVSTORE",
"endpoint": "myhost:8080",
}
Then you may use this file to create NoSQLClient instance:
import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient('/path/to/config.json');
As shown above, you may specify value for serviceType property as a string (as well as ServiceType constant in JavaScript code). See ServiceType for details.
To connect to the proxy in secure mode, in addition to communication endpoint, you need to specify user name and password of the driver user. This information is passed in auth object under kvstore property and can be specified in one of 3 ways as described below.
Note that in the examples below we will omit serviceType in configuration object/file because KVSTORE is assumed if auth object in the configuration contains only kvstore property.
You may choose to specify user name and password directly:
import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient({
endpoint: 'https://myhost:8081',
auth: {
kvstore: {
user: 'John',
password: johnsPassword
}
}
});
This option is less secure because the password is stored in plain text in memory.
You may choose to store credentials in a separate file which is protected by file system permissions, thus making it more secure than previous option, because the credentials will not be stored in memory, but will be accessed from this file only when login is needed.
Credentials file should have the following format:
{
"user": "<Driver user name>",
"password": "<Driver user password>"
}
Then you may reference this credentials file as following:
import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient({
endpoint: 'https://myhost:8081',
auth: {
kvstore: {
credentials: 'path/to/credentials.json'
}
}
});
You may also reference credentials.json in the configuration file used to create NoSQLClient instance as was shown for non-secure store:
config.json
{
"endpoint": "https://myhost:8081",
"auth": {
"kvstore": {
"credentials": "path/to/credentials.json"
}
}
}
import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient('/path/to/config.json');
You may implement your own credentials provider for secure storage and retrieval of driver credentials as an instance of KVStoreCredentialsProvider interface. Note that loadCredentials returns a Promise and can be implemented as an async function:
import { NoSQLClient } from 'oracle-nosqldb';
class MyKVStoreCredentialsProvider {
constructor() {
// Initialize required state information if needed
}
async loadCredentials() {
// Obtain client id, client secret, user name and user password somehow
return { // Return credentials object as a result
user: driverUserName,
password: driverPassword
};
}
}
let client = new NoSQLClient({
endpoint: 'https://myhost:8081',
auth: {
kvstore: {
credentials: new MyKVStoreCredentialsProvider(myArgs...)
}
}
});
You may return password as either Buffer (UTF8-encoded) or string, but it is advisable to use Buffer, because the driver will erase its contents once login is performed.
You may also set credentials property to a function with the signature of loadCredentials:
import { NoSQLClient } from 'oracle-nosqldb';
async function loadMyCredentials() {
//.....
}
let client = new NoSQLClient({
endpoint: 'ndcs.uscom-east-1.oraclecloud.com',
auth: {
kvstore: {
credentials: loadMyCredentials
}
}
});
The examples in the examples directory are configured to make it simple to connect and run against the On-Premise Oracle NoSQL Database.
In the examples/config directory, you will see a configuration file template kvstore_template.json. It is used as configuration file to create NoSQLClient instance as shown above. Make a copy of this file and fill in appropriate values. For a secure store, leave either user and password or the credentials property inside the kvstore object and remove the rest. For a non-secure store, remove all properties in the kvstore object or remove the auth property entirely.
Follow these steps:
An Oracle NoSQL Database instance must be running
A proxy server instance must be running, connected to the database
Edit the kvstore_template.json file as described above, based on the proxy configuration.
Here's an example of a config file for a not-secure, local proxy:
{
"serviceType": "KVSTORE",
"endpoint": "http://localhost:80"
}
An example of a config file for a secure proxy and store. Note that it may be necessary to configure your system so that node finds the required certificates. See Configuring the SDK for a Secure Store.
{
"serviceType": "KVSTORE",
"endpoint": "https://somehost:443",
"auth":
{
"kvstore":
{
"user": "driverUser",
"password": "driverPassword05@"
}
}
}
npm install
node <example.js> <config.json>
E.g.
npm install
$ node basic_example.js kvstore_config.json
Use npm to install the dependencies, then you can run each example as follows:
npm install
npx tsx <example.ts> <config.json>
E.g.
npm install
npx tsx single_row_ops.ts kvstore_config.json
The commands above use tsx which is installed as one of the dependencies.
Alternatively, you can build the examples into JavaScript. Then run the resulting .js files, which are created in the dist directory, e.g.:
npm run build
node dist/single_row_ops.js kvstore_config.json
See package.json for more details.
Generated using TypeDoc