OCI NodeJS Client for Distributed Database Service

Common errors

• Error: did not find a proper configuration for user

  cause The SDK could not locate or parse the OCI configuration file, or the specified profile is missing/invalid.
  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.

• ServiceError: NotAuthorizedOrNotFound. Authorization failed or requested resource not found.

  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.
  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.

• ETIMEDOUT

  cause A network timeout occurred, preventing the SDK from receiving a response from the OCI service within the configured timeout period.
  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.

• TypeError: Cannot read properties of undefined (reading 'items')

  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.
  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`).

Warnings

• breaking 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.
  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.
• gotcha 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.
  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).
• gotcha 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.
  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.
• gotcha 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).
  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.
• gotcha 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.
  Fix: Ensure your project's Node.js and TypeScript versions align with the SDK's supported versions to guarantee compatibility and stability.

Install

• npm install oci-distributeddatabase npm
• yarn add oci-distributeddatabase yarn
• pnpm add oci-distributeddatabase pnpm

Imports

• DistributedDatabaseClient
  wrong:

  const DistributedDatabaseClient = require('oci-distributeddatabase').DistributedDatabaseClient;

  correct:

  import { DistributedDatabaseClient } from 'oci-distributeddatabase';

  This is the primary client class for interacting with the Distributed Database Service.
• models
  wrong:

  import { models } from 'oci-distributeddatabase';

  correct:

  import * as models from 'oci-distributeddatabase/lib/model';

  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')`.
• ConfigFileAuthenticationDetailsProvider
  wrong:

  import { ConfigFileAuthenticationDetailsProvider } from 'oci-distributeddatabase';

  correct:

  import { ConfigFileAuthenticationDetailsProvider } from 'oci-common';

  Authentication providers are part of the `oci-common` package, not service-specific packages. Ensure `oci-common` is also installed.

Quickstart

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.

import { DistributedDatabaseClient } from 'oci-distributeddatabase';
import { ConfigFileAuthenticationDetailsProvider } from 'oci-common';
import * as models from 'oci-distributeddatabase/lib/model';

// Ensure OCI configuration is set up at ~/.oci/config or via environment variables.
// For programmatic configuration, ensure OCI_CONFIG_FILE and OCI_PROFILE_NAME are set,
// or provide explicit paths.
// For example:
// process.env.OCI_CONFIG_FILE = '~/.oci/config';
// process.env.OCI_PROFILE_NAME = 'DEFAULT';

const compartmentId = process.env.OCI_COMPARTMENT_ID ?? '';

async function listDistributedAutonomousDatabases() {
  if (!compartmentId) {
    console.error('Error: OCI_COMPARTMENT_ID environment variable is not set.');
    process.exit(1);
  }

  try {
    const provider = new ConfigFileAuthenticationDetailsProvider();
    const client = new DistributedDatabaseClient({ authenticationDetailsProvider: provider });

    console.log(`Listing Distributed Autonomous Databases in compartment: ${compartmentId}...`);

    const listRequest: models.ListDistributedAutonomousDatabasesRequest = {
      compartmentId: compartmentId,
      limit: 10 // Limiting results for brevity
    };

    const response = await client.listDistributedAutonomousDatabases(listRequest);

    if (response.distributedAutonomousDatabaseCollection.items.length > 0) {
      console.log('Found Distributed Autonomous Databases:');
      for (const db of response.distributedAutonomousDatabaseCollection.items) {
        console.log(`- ${db.displayName} (OCID: ${db.id}) - Lifecycle State: ${db.lifecycleState}`);
      }
    } else {
      console.log('No Distributed Autonomous Databases found in the specified compartment.');
    }
  } catch (error) {
    console.error('Failed to list Distributed Autonomous Databases:', error);
  }
}

listDistributedAutonomousDatabases();