Oracle NoSQL Database Node.js Driver

Common errors

• Error: Cannot find module 'oracle-nosqldb'

  cause The `oracle-nosqldb` package has not been installed or is not accessible in the current project's `node_modules`.
  fix Run `npm install oracle-nosqldb` in your project directory.

• Error: Missing authentication credentials.

  cause When connecting to Oracle NoSQL Database Cloud Service, the `auth` configuration in `NoSQLClient` is incomplete or incorrect, or OCI environment variables are not set.
  fix Provide all required OCI credentials (user OCID, tenant OCID, private key, fingerprint) in the `auth` object or ensure they are correctly sourced as environment variables. Check OCI IAM policies for necessary permissions.

• Error: connect ECONNREFUSED <address>:<port>

  cause The application failed to connect to the NoSQL Database proxy server, often due to the server not running, being on a different host/port, or firewall issues.
  fix Verify that the Oracle NoSQL Database proxy server is running, listening on the specified host and port (e.g., `localhost:8080`), and network firewalls are not blocking the connection.

• TypeError: Class constructor NoSQLClient cannot be invoked without 'new'

  cause The `NoSQLClient` class is being called as a function (e.g., `NoSQLClient(config)`) instead of instantiated with the `new` keyword.
  fix Always create an instance of `NoSQLClient` using `const client = new NoSQLClient(config);`.

Warnings

• gotcha The SDK requires Node.js version 12.0.0 or higher. Using older versions will result in runtime errors.
  Fix: Upgrade Node.js to version 12.0.0 or higher. LTS versions are generally recommended.
• gotcha When using TypeScript, version 5.0.x or higher is required for optimal type inference and compatibility with the shipped type declarations.
  Fix: Ensure TypeScript version 5.0.x or higher is installed in your project: `npm install typescript@^5.0.0`.
• gotcha Connecting to Oracle NoSQL Database Cloud Service necessitates proper Oracle Cloud Infrastructure (OCI) authentication configuration, including a user, group policy, and API signing keys. Incorrect credentials or policies will lead to authentication failures.
  Fix: Refer to OCI documentation for setting up API signing keys and IAM policies, and ensure `NoSQLClient` is initialized with the correct `auth` configuration.
• gotcha For on-premise Oracle NoSQL Database deployments, a running Oracle NoSQL Database instance and a separate NoSQL Proxy server are required for the Node.js SDK to connect. The SDK communicates via the HTTP proxy, not directly with the database nodes.
  Fix: Ensure both the Oracle NoSQL Database and the NoSQL Proxy are running and accessible from your application's host. Configure the `endpoint` in `NoSQLClient` accordingly.
• gotcha The quickstart examples and initial setup often assume a non-secure configuration for simplicity. Secure configurations for both cloud and on-premise environments are more complex and require additional setup for certificates, secure proxies, and authentication.
  Fix: Always review security best practices and configure secure connections (e.g., HTTPS for proxy, proper IAM for cloud) for production environments.

Install

• npm install oracle-nosqldb npm
• yarn add oracle-nosqldb yarn
• pnpm add oracle-nosqldb pnpm

Imports

• NoSQLClient
  wrong:

  const NoSQLClient = require('oracle-nosqldb');

  correct:

  import { NoSQLClient } from 'oracle-nosqldb';

  The NoSQLClient class is a named export, common in both ESM and CJS environments (using destructuring for CJS).
• Region
  wrong:

  import Region from 'oracle-nosqldb';

  correct:

  import { Region } from 'oracle-nosqldb';

  Region is a named export, not a default export. Incorrectly importing it as a default will fail.
• ServiceType
  wrong:

  const ServiceType = require('oracle-nosqldb');

  correct:

  import { ServiceType } from 'oracle-nosqldb';

  ServiceType is a named export. For CommonJS, ensure proper destructuring like `require('oracle-nosqldb').ServiceType`.

Quickstart

This quickstart demonstrates creating a table, inserting a record using `put()`, retrieving it with `get()`, and finally dropping the table. It provides configuration placeholders for both Oracle NoSQL Database Cloud Service and on-premise/simulator environments.

/*
 * A simple example that
 *   - creates a table
 *   - inserts a row using the put() operation
 *   - reads a row using the get() operation
 *   - drops the table
 *
 * To run:
 *  1. Edit for your target environment and credentials
 *  2. Run it:
 *       node quickstart.js cloud|cloudsim|kvstore
 *
 *  Use 'cloud' for the Oracle NoSQL Database Cloud Service
 *  Use 'cloudsim' for the Oracle NoSQL Cloud Simulator
 *  Use 'kvstore' for the Oracle NoSQL Database on-premise
 */
'use strict';

const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
const Region = require('oracle-nosqldb').Region;
const ServiceType = require('oracle-nosqldb').ServiceType;

// --- Configuration (replace with your actual credentials and endpoint) ---
// For Oracle NoSQL Database Cloud Service:
// const config = {
//   serviceType: ServiceType.CLOUD,
//   region: Region.US_PHOENIX_1, // e.g., Region.US_PHOENIX_1
//   auth: {
//     userName: process.env.OCI_USER_OCID ?? '',
//     tenantId: process.env.OCI_TENANT_OCID ?? '',
//     privateKey: process.env.OCI_PRIVATE_KEY_PATH ?? '',
//     fingerprint: process.env.OCI_FINGERPRINT ?? '',
//     passPhrase: process.env.OCI_PRIVATE_KEY_PASSPHRASE ?? '' // Optional
//   }
// };

// For Oracle NoSQL Cloud Simulator or On-Premise:
const config = {
  serviceType: ServiceType.KVSTORE,
  endpoint: process.env.NOSQL_ENDPOINT ?? 'localhost:8080' // Default for simulator/on-prem
};

async function runQuickstart() {
  let client;
  try {
    client = new NoSQLClient(config);
    const tableName = 'quickstartTable';

    console.log(`Creating table: ${tableName}`);
    await client.tableDDL(`CREATE TABLE ${tableName} (id LONG, name STRING, PRIMARY KEY (id))`);
    console.log('Table created.');

    const row = { id: 1, name: 'Hello, Oracle NoSQL!' };
    console.log(`Putting row: ${JSON.stringify(row)}`);
    await client.put(tableName, row);
    console.log('Row put.');

    console.log(`Getting row with id: ${row.id}`);
    const result = await client.get(tableName, { id: row.id });
    console.log(`Got row: ${JSON.stringify(result.value)}`);

    console.log(`Dropping table: ${tableName}`);
    await client.tableDDL(`DROP TABLE ${tableName}`);
    console.log('Table dropped.');

  } catch (error) {
    console.error('Error:', error.message);
  } finally {
    if (client) {
      client.close();
    }
  }
}

runQuickstart();