This guide describes how to install, configure, and use the Oracle NoSQL Database Node.js SDK with the Oracle NoSQL Database Cloud Service.
The SDK requires:
You can install the SDK from the npm registry, or alternatively from GitHub.
You may install the 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
The SDK requires an Oracle Cloud account and a subscription to the Oracle NoSQL Database Cloud Service. If you do not already have an Oracle Cloud account you can start here.
The SDK is using Oracle Cloud Infrastructure Identity and Access Management (IAM) to authorize database operations. For more information on IAM see Overview of Oracle Cloud Infrastructure Identity and Access Management
To use the SDK, you need to configure it for use with IAM. The best way to get started with the service is to use your Oracle Cloud user's identity to obtain required credentials and provide them to the application. This is applicable in most use cases and described below in section Authorize with Oracle Cloud User's Identity.
A different configuration that does not require user's credentials may be used in a couple of special use cases:
To access Oracle NoSQL Database Cloud Service from a compute instance in the Oracle Cloud Infrastructure (OCI), use Instance Principal. See Authorizing with Instance Principal.
To access Oracle NoSQL Database Cloud Service from other Oracle Cloud service resource such as Functions, use Resource Principal. See Authorizing with Resource Principal.
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.
See sections below on how to aquire credentials and configure the application to connect to Oracle NoSQL Database Cloud Service. You may also need to perform additional configuration such as choosing your region, specifying compartment and other configuration options.
See Example Quick Start for the quickest way to get an example running.
See Authentication to connect to Oracle NoSQL Database for details of credentials you will need to configure an application.
These steps only need to be performed one time for a user. If they have already been done they can be skipped. You need to obtain the following credentials:
Credentials are used to authorize your application to use the service. There are 3 ways to supply credentials:
The configuration object used to create NoSQLClient instance (see Connecting an Application) will indicate how the driver obtains the credentials and will be different depending on which of the above options is chosen.
Creating IAMCredentialsProvider is the most secure option, because you are in control of how credentials are stored and loaded by the driver. Otherwise, the recommended option is to use an Oracle Cloud Infrastructure configuration file. Supplying credentials directly in a configuration object is less secure because sensitive information such as private key will be kept in memory for the duration of the NoSQLClient instance.
You can store the credentials in an Oracle Cloud Infrastructure configuration file.
The default path for the configuration file is ~/.oci/config. The file may contain multiple profiles. By default, the SDK uses profile named DEFAULT to store the credentials.
To use these default values, create file named config in ~/.oci directory with the following contents:
[DEFAULT]
tenancy=<your-tenancy-ocid>
user=<your-user-ocid>
fingerprint=<fingerprint-of-your-public-key>
key_file=<path-to-your-private-key-file>
pass_phrase=<your-private-key-passphrase>
region=<your-region-identifier>
Note that you may also specify your region identifier together with credentials in the OCI configuration file. The driver will look at the location above by default, and if a region is provided together with credentials, you do not need to provide initial configuration and can use the no-argument constructor:
import { NoSQLClient } from 'oracle-nosqldb';
let client = new NoSQLClient();
Alternatively, you may choose to specify the region in the configuration:
import { NoSQLClient } from 'oracle-nosqldb';
let client = new NoSQLClient({ region: Region.US_ASHBURN_1 });
You may choose to use different path for OCI configuration file as well as different profile within the configuration file. In this case, specify these within auth.iam property of the initial configuration (see IAMConfig). For example, if your OCI configuration file path is ~/myapp/.oci/config and you store your credentials under profile Jane:
...............
...............
[Jane]
tenancy=.......
user=..........
...............
[John]
tenancy=.......
user=..........
...............
Then create NoSQLClient instance as follows:
import { NoSQLClient } from 'oracle-nosqldb';
let client = new NoSQLClient({
region: Region.US_ASHBURN_1,
auth: {
iam: {
configFile: '~/myapp/.oci/config',
profileName: 'Jane'
}
}
});
(Note that you don't have to specify service type if you specified auth.iam property, see section Specifying Service Type)
You may specify credentials directly as part of auth.iam property in the initial configuration (see IAMConfig). Create NoSQLClient instance as follows:
import { NoSQLClient } from 'oracle-nosqldb';
let client = new NoSQLClient({
region: <your-service-region>
auth: {
iam: {
tenantId: myTenancyOCID,
userId: myUserOCID,
fingerprint: myPublicKeyFingerprint,
privateKeyFile: myPrivateKeyFile,
passphrase: myPrivateKeyPassphrase
}
}
});
You may implement your own credentials provider for secure storage and retrieval of IAMCredentials as an instance of IAMCredentialsProvider interface. loadCredentials returns a Promise of IAMCredentials and thus can be implemented as an async function.
import { NoSQLClient } from 'oracle-nosqldb';
class MyIAMCredentialsProvider {
constructor() {
// Initialize required state information if needed
}
async loadCredentials() {
.......... //retrieve credentials in preferred manner
..........
return {
tenantId: myTenancyOCID,
userId: myUserOCID,
fingerprint: myPublicKeyFingerprint,
privateKey: myPEMPrivateKeyData
};
}
}
let client = new NoSQLClient({
region: Region.US_ASHBURN_1,
auth: {
iam: {
credentialsProvider: new MyIAMCredentialsProvider(myArgs...)
}
}
});
It is advised that properties such as privateKey and passphrase returned by IAMCredentialsProvider be instances of Buffer rather than strings in which case that the driver will clear them right after they are used.
You may also set credentialsProvider property to a function with the signature of loadCredentials:
import { NoSQLClient } from 'oracle-nosqldb';
async function loadMyCredentials() {
//.....
}
let client = new NoSQLClient({
region: Region.US_ASHBURN_1,
auth: {
iam: {
credentialsProvider: loadMyCredentials
}
}
});
You may also specify credentialsProvider property as string, in which case it specifies a module name or path that exports IAMCredentialsProvider. This will allow you to store initial configuration in a JSON file (see Connecting an Application). Note that the provider (whether as an object or a function) should be that module's sole export.
Instance Principal is an IAM service feature that enables instances to be authorized actors (or principals) to perform actions on service resources. Each compute instance has its own identity, and it authenticates using the certificates that are added to it. See Calling Services from an Instance for prerequisite steps to set up Instance Principal.
Once set up, create NoSQLClient instance as follows:
import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient({
region: Region.US_ASHBURN_1,
compartment: 'ocid1.compartment.oc1.............................'
auth: {
iam: {
useInstancePrincipal: true
}
}
});
You may also use JSON config file with the same configuration as described in Connecting an Application.
Note that when using Instance Principal you must specify compartment id (OCID) as compartment property (see Specifying a Compartment). This is required even if you wish to use default compartment. Note that you must use compartment id and not compartment name or path. In addition, when using Instance Principal, you may not prefix table name with compartment name or path when calling NoSQLClient APIs.
Resource Principal is an IAM service feature that enables the resources to be authorized actors (or principals) to perform actions on service resources. You may use Resource Principal when calling Oracle NoSQL Database Cloud Service from other Oracle Cloud service resource such as Functions. See Accessing Other Oracle Cloud Infrastructure Resources from Running Functions for how to set up Resource Principal.
Once set up, create NoSQLClient instance as follows:
import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient({
region: Region.US_ASHBURN_1,
compartment: 'ocid1.compartment.oc1.............................'
auth: {
iam: {
useResourcePrincipal: true
}
}
});
You may also use JSON config file with the same configuration as described in Connecting an Application.
Note that when using Resource Principal you must specify compartment id (OCID) as compartment property (see Specifying a Compartment). This is required even if you wish to use default compartment. Note that you must use compartment id and not compartment name or path. In addition, when using Resource Principal, you may not prefix table name with compartment name or path when calling NoSQLClient APIs.
The first step in your Oracle NoSQL Database Cloud Service 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 a JSON file that contains the same configuration information as in Config.
The required information consists of the communication region or endpoint and authorization information described in section Acquire Credentials for the Oracle NoSQL Database Cloud Service (also see AuthConfig).
It is possible to specify a Region or a string endpoint, but not both. If you use a Region the endpoint of that Region is inferred. If an endpoint is used it needs to be either the endpoint of a Region or a reference to a host and port. For example when using the Cloud Simulator you would use an endpoint string like http://localhost:8080. Other, optional parameters may be specified as well. See API documentation for NoSQLClient, Config and AuthConfig for more information.
For example, to specify the configuration as an object:
import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient({
region: Region.US_ASHBURN_1,
auth: {
iam: {
configFile: '~/myapp/.oci/config',
profileName: 'Jane'
}
}
});
You may choose to store the same configuration in a JSON file. Create file config.json with following contents:
{
"region": "US_ASHBURN_1",
"auth":
{
"iam":
{
"configFile": "~/myapp/.oci/config",
"profileName": "Jane"
}
}
}
Then you may create NoSQLClient instance as follows:
import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient('/path/to/config.json');
In the examples directory, you will see JSON configuration files that are used to create a NoSQLClient instance as shown above:
Alternatively, you may create NoSQLClient instance for the cloud service with no-argument constructor (without config parameter) if you are using a default configuration file and default profile containing the credentials and the region as described in section Using a Configuration File.
Because this SDK is used both for the Oracle NoSQL Cloud Service and the On-Premise Oracle NoSQL Database, the Config object can specify that we are connecting to the cloud service by setting serviceType property to CLOUD. You can always explicitly specify the serviceType property, but in cases such in code snippets above where the configuration contains the region, where configuration has auth object that contains iam property or where an initial configuration is not provided (because the region is specified in OCI configuration file) the service type will be deduced by the driver. See ServiceType for details.
You may need to specify the service type explicitly as CLOUD only if the auth.iam is not present in the configuration (such as when using OCI configuration file with default profile for credentials) and the configuration specifies endpoint instead of region. It is recommended to use region instead of endpoint for Cloud Service.
Note that the configuration containing endpoint and not containing either serviceType or auth will default to CLOUDSIM (see Using the Cloud Simulator).
You may specify service type either as ServiceType enumeration constant (in code) or as a string (in code and in JSON file). For example, when using the default configuration file and default profile:
In code:
import { NoSQLClient, ServiceType } from 'oracle-nosqldb';
const client = new NoSQLClient({
serviceType: ServiceType.CLOUD,
region: Region.US_ASHBURN_1
});
In JSON configuration file:
{
"serviceType": "CLOUD",
"region": "us-ashburn-1"
}
In the Oracle NoSQL Cloud Service environment tables are always created in an Oracle Cloud Infrastructure compartment (see Managing Compartments). It is recommended that compartments be created for tables to better organize them and control security, which is a feature of compartments.The default compartment for tables is the root compartment of the user's tenancy. A default compartment for all requests performed on a handle can be specified by setting the compartment property. For example, to specify a default compartment:
import { NoSQLClient } from 'oracle-nosqldb';
const client = new NoSQLClient({
region: Region.US_ASHBURN_1,
compartment: 'mycompartment'
});
The string value may be either a compartment id or a compartment name or path. If it is a simple name it must specify a top-level compartment. If it is a path to a nested compartment, the top-level compartment must be excluded as it is inferred from the tenancy.
A compartment can also be specified in each request in the options object. This value overrides the initial configuration value.
The examples in the examples directory are configured to make it simple to connect and run against the Oracle NoSQL Database Cloud Service. Follow these steps:
[DEFAULT]
tenancy=<your-tenancy-ocid>
user=<your-user-ocid>
fingerprint=<fingerprint-of-your-public-key>
key_file=<path-to-your-private-key-file>
pass_phrase=<your-private-key-passphrase>
region=<your-region-identifier>
Alternatively, you may create your own JSON config file to pass to the examples. Each example takes a JSON config file path as an optional first command line parameter. Config file templates are in examples/config directory. Make a copy of cloud_template.json, fill in appropriate properties and remove any unused properties.
Instead of using a configuration file it is possible to modify the example code to directly provide your credentials as described in Specifying Credentials Directly.
npm install
node <example.js> [optional_config_file.json]
e.g.
npm install
node basic_example.js
Use npm to install the dependencies, then you can run each example as follows:
npm install
npx tsx <example.ts> [optional_config_file.json]
E.g.
npm install
npx tsx single_row_ops.ts
The commands above use tsx which is installed as one of the dependencies.
The last parameter is an optional JSON config file (only needed if not using default OCI config file as described above), e.g.:
npx tsx single_row_ops.ts config.json
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
See package.json for more details.
The configuration instructions above are for getting connected to the actual Oracle NoSQL Database Cloud Service.
You may first get familiar with Oracle NoSQL Database Node.js SDK and its interfaces by using the Oracle NoSQL Cloud Simulator.
The Cloud Simulator simulates the cloud service and lets you write and test applications locally without accessing Oracle NoSQL Database Cloud Service.
You can start developing your application with the Oracle NoSQL Cloud Simulator, using and understanding the basic examples, before you get started with the Oracle NoSQL Database Cloud Service. After building, debugging, and testing your application with the Oracle NoSQL Cloud Simulator, move your application to the Oracle NoSQL Database Cloud Service.
Follow these instructions to run an example program against the Cloud Simulator:
Download and start the Cloud Simulator.
Copy and edit cloudsim.json configuration file in examples/config directory and modify the endpoint if using a non-default port or if it is running on another machine. If using default settings, you may use the file cloudsim.json as it is.
It should look like this:
{
"endpoint": "http://localhost:8080"
}
Run a JavaScript example in examples/javascript directory using the syntax:
node <example.js> <config.json>
e.g.
node basic_example.js ../config/cloudsim.json
Run a TypeScript example in examples/typescript directory using the syntax:
npx tsx <example.ts> -- <config.json>
e.g.
npx tsx single_row_ops.ts -- ../cloudsim.json
Note that the Cloud Simulator does not require authorization information and credentials described above that are required by Oracle NoSQL Database Cloud Service. Only the endpoint is required and is by default localhost:8080. The service type for Cloud Simulator is CLOUDSIM. It is a default service type when authorization information is not present, so the configuration that contains only endpoint property will be interpreted as configuration for Cloud Simulator. See ServiceType and cloudsim.json in examples directory.
Generated using TypeDoc