{"id":16467,"library":"oci-distributeddatabase","title":"OCI NodeJS Client for Distributed Database Service","description":"The `oci-distributeddatabase` package provides the TypeScript and JavaScript client for managing resources within Oracle Cloud Infrastructure's (OCI) Distributed Database Service. This service is designed for deploying and managing Globally Distributed Databases and Globally Distributed Autonomous Databases, which offer linearly scalable, multi-model database solutions ensuring high availability, low latency, and adherence to data sovereignty requirements. The current stable version is 2.130.0, with Oracle maintaining a frequent release cadence, often aligning security updates with their Critical Patch Update program. As part of the broader OCI SDK, it leverages a consistent authentication and configuration model across all OCI services. It's built for Node.js environments (supporting versions 14, 16, 18, 20) and ships with TypeScript type definitions, but it does not support browser environments.","status":"active","version":"2.130.0","language":"javascript","source_language":"en","source_url":"https://github.com/oracle/oci-typescript-sdk","tags":["javascript","typescript"],"install":[{"cmd":"npm install oci-distributeddatabase","lang":"bash","label":"npm"},{"cmd":"yarn add oci-distributeddatabase","lang":"bash","label":"yarn"},{"cmd":"pnpm add oci-distributeddatabase","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides core authentication, request signing, and common utilities for all OCI SDK services.","package":"oci-common","optional":false}],"imports":[{"note":"This is the primary client class for interacting with the Distributed Database Service.","wrong":"const DistributedDatabaseClient = require('oci-distributeddatabase').DistributedDatabaseClient;","symbol":"DistributedDatabaseClient","correct":"import { DistributedDatabaseClient } from 'oci-distributeddatabase';"},{"note":"Import specific models and types for requests and responses from the `lib/model` submodule. The CommonJS `require` equivalent would be `require('oci-distributeddatabase/lib/model')`.","wrong":"import { models } from 'oci-distributeddatabase';","symbol":"models","correct":"import * as models from 'oci-distributeddatabase/lib/model';"},{"note":"Authentication providers are part of the `oci-common` package, not service-specific packages. Ensure `oci-common` is also installed.","wrong":"import { ConfigFileAuthenticationDetailsProvider } from 'oci-distributeddatabase';","symbol":"ConfigFileAuthenticationDetailsProvider","correct":"import { ConfigFileAuthenticationDetailsProvider } from 'oci-common';"}],"quickstart":{"code":"import { DistributedDatabaseClient } from 'oci-distributeddatabase';\nimport { ConfigFileAuthenticationDetailsProvider } from 'oci-common';\nimport * as models from 'oci-distributeddatabase/lib/model';\n\n// Ensure OCI configuration is set up at ~/.oci/config or via environment variables.\n// For programmatic configuration, ensure OCI_CONFIG_FILE and OCI_PROFILE_NAME are set,\n// or provide explicit paths.\n// For example:\n// process.env.OCI_CONFIG_FILE = '~/.oci/config';\n// process.env.OCI_PROFILE_NAME = 'DEFAULT';\n\nconst compartmentId = process.env.OCI_COMPARTMENT_ID ?? '';\n\nasync function listDistributedAutonomousDatabases() {\n  if (!compartmentId) {\n    console.error('Error: OCI_COMPARTMENT_ID environment variable is not set.');\n    process.exit(1);\n  }\n\n  try {\n    const provider = new ConfigFileAuthenticationDetailsProvider();\n    const client = new DistributedDatabaseClient({ authenticationDetailsProvider: provider });\n\n    console.log(`Listing Distributed Autonomous Databases in compartment: ${compartmentId}...`);\n\n    const listRequest: models.ListDistributedAutonomousDatabasesRequest = {\n      compartmentId: compartmentId,\n      limit: 10 // Limiting results for brevity\n    };\n\n    const response = await client.listDistributedAutonomousDatabases(listRequest);\n\n    if (response.distributedAutonomousDatabaseCollection.items.length > 0) {\n      console.log('Found Distributed Autonomous Databases:');\n      for (const db of response.distributedAutonomousDatabaseCollection.items) {\n        console.log(`- ${db.displayName} (OCID: ${db.id}) - Lifecycle State: ${db.lifecycleState}`);\n      }\n    } else {\n      console.log('No Distributed Autonomous Databases found in the specified compartment.');\n    }\n  } catch (error) {\n    console.error('Failed to list Distributed Autonomous Databases:', error);\n  }\n}\n\nlistDistributedAutonomousDatabases();","lang":"typescript","description":"This quickstart demonstrates how to initialize the OCI Distributed Database client, authenticate using a configuration file, and then list Distributed Autonomous Databases within a specified OCI compartment."},"warnings":[{"fix":"Review the `CHANGELOG.md` file in the `oci-typescript-sdk` repository or your installed package for specific breaking changes. Update your code to reflect the new API surface.","message":"The OCI TypeScript/JavaScript SDK frequently introduces breaking changes in minor versions, often involving removal or renaming of fields and models within specific service client packages. Always consult the CHANGELOG.md for the specific version before upgrading.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Be aware of this limitation when handling large numbers. If exact large integer representation is critical, consider treating such values as strings if the service API permits, or implement custom big integer parsing if necessary (though current impact on API calls is minimal).","message":"The SDK for TypeScript/JavaScript has a known issue with potential data rounding for numbers exceeding JavaScript's `Number.MAX_SAFE_INTEGER`. This can affect large integer values returned by OCI services.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use the OCI SDK solely within Node.js applications or server-side functions. For client-side interactions with OCI, utilize the OCI REST APIs directly or a suitable proxy.","message":"The OCI TypeScript/JavaScript SDK is designed exclusively for Node.js environments and does not support running in web browsers. Attempts to use it in a browser context will result in runtime errors.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure your OCI user or instance principal has the necessary IAM policies for the specific Distributed Database Service operations. Verify that your `~/.oci/config` file is correctly set up, the specified profile exists, and the API signing key is valid and uploaded to OCI.","message":"Incorrect OCI IAM policies or misconfigured credentials (e.g., missing `~/.oci/config` file, invalid profile, incorrect key pair) are common causes of errors, often manifesting as 'Not Authorized' or 'Not Found' (due to lack of permission to even see the resource).","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure your project's Node.js and TypeScript versions align with the SDK's supported versions to guarantee compatibility and stability.","message":"Using unsupported Node.js or TypeScript versions can lead to unexpected behavior or compilation issues. The SDK currently supports Node.js 14, 16, 18, 20 and TypeScript 4.1.3.","severity":"gotcha","affected_versions":"<2.0.0 (older versions might have different requirements)"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify that `~/.oci/config` exists and is accessible, the `[DEFAULT]` profile or the specified profile is correctly configured, and the necessary environment variables (`OCI_CONFIG_FILE`, `OCI_PROFILE_NAME`) are set if not using the default location/profile.","cause":"The SDK could not locate or parse the OCI configuration file, or the specified profile is missing/invalid.","error":"Error: did not find a proper configuration for user"},{"fix":"Check OCI IAM policies for the user/group associated with the credentials. Ensure policies grant appropriate `manage` or `read` permissions for `globally-distributed-database-family` or specific resources within the target compartment. Double-check resource OCIDs and compartment IDs.","cause":"The OCI user/instance principal lacks the necessary IAM permissions to perform the requested operation or access the resource, or the resource genuinely does not exist.","error":"ServiceError: NotAuthorizedOrNotFound. Authorization failed or requested resource not found."},{"fix":"Increase the client's timeout setting if appropriate, check network connectivity to OCI endpoints, verify region configuration, and ensure no firewalls or proxies are blocking traffic.","cause":"A network timeout occurred, preventing the SDK from receiving a response from the OCI service within the configured timeout period.","error":"ETIMEDOUT"},{"fix":"Add robust checks for `null` or `undefined` on API response objects and their properties. Ensure the service operation was successful before attempting to access nested data. This can sometimes indicate an underlying authorization issue (see `NotAuthorizedOrNotFound`).","cause":"Often occurs when an API response structure is unexpected, frequently due to an empty or malformed response object from the OCI service, or incorrect access of response properties.","error":"TypeError: Cannot read properties of undefined (reading 'items')"}],"ecosystem":"npm"}