{"id":17321,"library":"oracle-nosqldb","title":"Oracle NoSQL Database Node.js Driver","description":"The `oracle-nosqldb` package provides the Node.js SDK for interacting with Oracle NoSQL Database, supporting both the Oracle NoSQL Database Cloud Service and on-premise deployments. Currently at version 5.5.3, the library offers comprehensive interfaces for developing JavaScript and TypeScript applications, enabling operations like table creation, data insertion, retrieval, and schema management. While a strict release cadence isn't specified, it appears to follow major Node.js ecosystem updates and NoSQL database feature releases. A key differentiator is its dual support for cloud and and on-premise environments, offering a consistent API across deployment models. Developers need Node.js 12 or higher, and for TypeScript projects, TypeScript 5.0.x or higher is recommended.","status":"active","version":"5.5.3","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","oracle","cloud","oracle-cloud","nosql","database","typescript"],"install":[{"cmd":"npm install oracle-nosqldb","lang":"bash","label":"npm"},{"cmd":"yarn add oracle-nosqldb","lang":"bash","label":"yarn"},{"cmd":"pnpm add oracle-nosqldb","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The NoSQLClient class is a named export, common in both ESM and CJS environments (using destructuring for CJS).","wrong":"const NoSQLClient = require('oracle-nosqldb');","symbol":"NoSQLClient","correct":"import { NoSQLClient } from 'oracle-nosqldb';"},{"note":"Region is a named export, not a default export. Incorrectly importing it as a default will fail.","wrong":"import Region from 'oracle-nosqldb';","symbol":"Region","correct":"import { Region } from 'oracle-nosqldb';"},{"note":"ServiceType is a named export. For CommonJS, ensure proper destructuring like `require('oracle-nosqldb').ServiceType`.","wrong":"const ServiceType = require('oracle-nosqldb');","symbol":"ServiceType","correct":"import { ServiceType } from 'oracle-nosqldb';"}],"quickstart":{"code":"/*\n * A simple example that\n *   - creates a table\n *   - inserts a row using the put() operation\n *   - reads a row using the get() operation\n *   - drops the table\n *\n * To run:\n *  1. Edit for your target environment and credentials\n *  2. Run it:\n *       node quickstart.js cloud|cloudsim|kvstore\n *\n *  Use 'cloud' for the Oracle NoSQL Database Cloud Service\n *  Use 'cloudsim' for the Oracle NoSQL Cloud Simulator\n *  Use 'kvstore' for the Oracle NoSQL Database on-premise\n */\n'use strict';\n\nconst NoSQLClient = require('oracle-nosqldb').NoSQLClient;\nconst Region = require('oracle-nosqldb').Region;\nconst ServiceType = require('oracle-nosqldb').ServiceType;\n\n// --- Configuration (replace with your actual credentials and endpoint) ---\n// For Oracle NoSQL Database Cloud Service:\n// const config = {\n//   serviceType: ServiceType.CLOUD,\n//   region: Region.US_PHOENIX_1, // e.g., Region.US_PHOENIX_1\n//   auth: {\n//     userName: process.env.OCI_USER_OCID ?? '',\n//     tenantId: process.env.OCI_TENANT_OCID ?? '',\n//     privateKey: process.env.OCI_PRIVATE_KEY_PATH ?? '',\n//     fingerprint: process.env.OCI_FINGERPRINT ?? '',\n//     passPhrase: process.env.OCI_PRIVATE_KEY_PASSPHRASE ?? '' // Optional\n//   }\n// };\n\n// For Oracle NoSQL Cloud Simulator or On-Premise:\nconst config = {\n  serviceType: ServiceType.KVSTORE,\n  endpoint: process.env.NOSQL_ENDPOINT ?? 'localhost:8080' // Default for simulator/on-prem\n};\n\nasync function runQuickstart() {\n  let client;\n  try {\n    client = new NoSQLClient(config);\n    const tableName = 'quickstartTable';\n\n    console.log(`Creating table: ${tableName}`);\n    await client.tableDDL(`CREATE TABLE ${tableName} (id LONG, name STRING, PRIMARY KEY (id))`);\n    console.log('Table created.');\n\n    const row = { id: 1, name: 'Hello, Oracle NoSQL!' };\n    console.log(`Putting row: ${JSON.stringify(row)}`);\n    await client.put(tableName, row);\n    console.log('Row put.');\n\n    console.log(`Getting row with id: ${row.id}`);\n    const result = await client.get(tableName, { id: row.id });\n    console.log(`Got row: ${JSON.stringify(result.value)}`);\n\n    console.log(`Dropping table: ${tableName}`);\n    await client.tableDDL(`DROP TABLE ${tableName}`);\n    console.log('Table dropped.');\n\n  } catch (error) {\n    console.error('Error:', error.message);\n  } finally {\n    if (client) {\n      client.close();\n    }\n  }\n}\n\nrunQuickstart();","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade Node.js to version 12.0.0 or higher. LTS versions are generally recommended.","message":"The SDK requires Node.js version 12.0.0 or higher. Using older versions will result in runtime errors.","severity":"gotcha","affected_versions":"<12.0.0"},{"fix":"Ensure TypeScript version 5.0.x or higher is installed in your project: `npm install typescript@^5.0.0`.","message":"When using TypeScript, version 5.0.x or higher is required for optimal type inference and compatibility with the shipped type declarations.","severity":"gotcha","affected_versions":"<5.0.x"},{"fix":"Refer to OCI documentation for setting up API signing keys and IAM policies, and ensure `NoSQLClient` is initialized with the correct `auth` configuration.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always review security best practices and configure secure connections (e.g., HTTPS for proxy, proper IAM for cloud) for production environments.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run `npm install oracle-nosqldb` in your project directory.","cause":"The `oracle-nosqldb` package has not been installed or is not accessible in the current project's `node_modules`.","error":"Error: Cannot find module 'oracle-nosqldb'"},{"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.","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.","error":"Error: Missing authentication credentials."},{"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.","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.","error":"Error: connect ECONNREFUSED <address>:<port>"},{"fix":"Always create an instance of `NoSQLClient` using `const client = new NoSQLClient(config);`.","cause":"The `NoSQLClient` class is being called as a function (e.g., `NoSQLClient(config)`) instead of instantiated with the `new` keyword.","error":"TypeError: Class constructor NoSQLClient cannot be invoked without 'new'"}],"ecosystem":"npm","meta_description":null}