Oracle Cloud Infrastructure (OCI) Globally Distributed Database Client

Common errors

• NotAuthorizedOrNotFound

  cause The configured user or instance principal lacks the necessary IAM permissions to perform the requested operation, or the specified resource (e.g., compartment, sharded database) does not exist or is in a different region.
  fix Verify IAM policies grant 'manage' or 'read' permissions for `globally-distributed-database` resources in the target compartment. Double-check the OCID of the resource or compartment and ensure the client's configured region matches the resource's region.

• Error: Cannot find module 'oci-globallydistributeddatabase'

  cause The package is not installed or the import path is incorrect, especially in projects mixing ESM and CJS modules.
  fix Run `npm install oci-globallydistributeddatabase` to install the package. If using ESM, ensure your `package.json` has `"type": "module"` or use `.mjs` extension, and ensure your `tsconfig.json` (if applicable) is configured for ESM imports (`"module": "NodeNext"`, `"moduleResolution": "NodeNext"`).

• TypeError: client.listShardedDatabases is not a function

  cause The `listShardedDatabases` method or the `GloballyDistributedDatabaseClient` object might be incorrectly instantiated or imported.
  fix Ensure `GloballyDistributedDatabaseClient` is correctly imported and initialized with an `authenticationDetailsProvider`. Verify the method name `listShardedDatabases` is spelled correctly and matches the SDK's API.

Warnings

• gotcha Authentication details are critical. Incorrect OCI configuration (missing private key, wrong tenancy OCID, user OCID, or fingerprint) or misconfigured IAM policies will result in `NotAuthorizedOrNotFound` errors.
  Fix: Ensure your `~/.oci/config` file is correctly set up with the required profile. Verify the user has the necessary IAM permissions (policies) for the specific OCI service API calls being made. Use `Auth.ConfigFileAuthenticationDetailsProvider` for local development or `Auth.InstancePrincipalsAuthenticationDetailsProvider` for compute instances.
• gotcha OCI SDKs default to a specific region (typically `us-ashburn-1` if not specified). If your resources are in a different region, you must explicitly set the region for the client, otherwise, you may encounter `NotFound` errors or requests routed to the wrong data center.
  Fix: Initialize the client with the correct region, e.g., `new GloballyDistributedDatabaseClient({ authenticationDetailsProvider: provider, region: common.Region.PHOENIX_1 });` or ensure the region is set in your OCI config file.
• gotcha List operations in OCI SDKs are often paginated. If you expect more results than the default `limit` (typically 10-100), you must implement pagination logic to fetch all items by repeatedly calling the list method with the `opcNextPage` token.
  Fix: Implement a loop that checks `response.opcNextPage` after each list call. If present, set it as `page` in the next request object to retrieve the subsequent page of results until `opcNextPage` is null.

Install

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

Imports

• GloballyDistributedDatabaseClient
  wrong:

  const GloballyDistributedDatabaseClient = require('oci-globallydistributeddatabase');

  correct:

  import { GloballyDistributedDatabaseClient } from 'oci-globallydistributeddatabase';

  Primary client class for interacting with the Globally Distributed Database service. CommonJS `require` is not the idiomatic way for newer OCI SDK versions.
• Auth
  wrong:

  import { Auth } from 'oci-globallydistributeddatabase';

  correct:

  import * as common from 'oci-common';
  const provider = new common.Auth.ConfigFileAuthenticationDetailsProvider();

  Authentication details providers (like `ConfigFileAuthenticationDetailsProvider` or `InstancePrincipalsAuthenticationDetailsProvider`) are typically found in the `oci-common` package, not directly within service-specific modules. It's best practice to import `oci-common` as a whole or specifically the `Auth` namespace.
• ListShardedDatabasesRequest
  wrong:

  import { ListShardedDatabasesRequest } from 'oci-globallydistributeddatabase/lib/globallydistributeddatabase_request';

  correct:

  import { GloballyDistributedDatabaseRequests } from 'oci-globallydistributeddatabase';
  const request: GloballyDistributedDatabaseRequests.ListShardedDatabasesRequest = {};

  Request and response types are nested under their respective service namespaces (e.g., `GloballyDistributedDatabaseRequests`, `GloballyDistributedDatabaseResponses`) for better organization and to prevent naming conflicts.

Quickstart

This quickstart demonstrates how to instantiate the `GloballyDistributedDatabaseClient`, configure authentication using the OCI config file, and list sharded databases within a specified OCI compartment.

import { GloballyDistributedDatabaseClient } from 'oci-globallydistributeddatabase';
import * as common from 'oci-common';
import { GloballyDistributedDatabaseRequests } from 'oci-globallydistributeddatabase';

async function listGloballyDistributedDatabases() {
  try {
    // Configure authentication using a config file (typically ~/.oci/config)
    // Ensure your OCI config file is set up with a profile.
    const provider = new common.Auth.ConfigFileAuthenticationDetailsProvider();

    // Initialize the client
    const client = new GloballyDistributedDatabaseClient({ authenticationDetailsProvider: provider });

    // Construct a list request. A compartmentId is typically required for listing resources.
    // Replace 'ocid1.compartment.oc1..aaaa...' with your actual compartment OCID.
    const compartmentId = process.env.OCI_COMPARTMENT_ID ?? 'ocid1.compartment.oc1..examplecompartmentid'; 
    
    const listRequest: GloballyDistributedDatabaseRequests.ListShardedDatabasesRequest = {
      compartmentId: compartmentId,
      limit: 10 // Optional: limit the number of results
    };

    // Make the API call to list sharded databases
    console.log(`Listing sharded databases in compartment: ${compartmentId}...`);
    const response = await client.listShardedDatabases(listRequest);

    // Process the response
    if (response.shardedDatabaseCollection?.items && response.shardedDatabaseCollection.items.length > 0) {
      console.log('Found Sharded Databases:');
      response.shardedDatabaseCollection.items.forEach(db => {
        console.log(`- Name: ${db.displayName}, ID: ${db.id}, Lifecycle State: ${db.lifecycleState}`);
      });
    } else {
      console.log('No sharded databases found in the specified compartment.');
    }
  } catch (error) {
    console.error('Error listing sharded databases:', error);
    // Log specific OCI errors for better debugging
    if (error instanceof common.Error.ServiceError) {
      console.error(`OCI Service Error: ${error.statusCode} - ${error.serviceCode} (${error.errorCode}): ${error.message}`);
    }
    process.exit(1);
  }
}

listGloballyDistributedDatabases();