{"id":16469,"library":"oci-globallydistributeddatabase","title":"Oracle Cloud Infrastructure (OCI) Globally Distributed Database Client","description":"This module, `oci-globallydistributeddatabase`, provides the NodeJS client for interacting with the Oracle Cloud Infrastructure (OCI) Globally Distributed Database Service. It is part of the larger `oci-typescript-sdk` and allows programmatic management of sharded databases, enabling operations like creating, updating, and listing globally distributed database resources within OCI. The current package version is 2.124.0, though the overall OCI SDK has seen rapid development with releases up to 2.130.0, indicating a highly active release cadence (often weekly or bi-weekly patches/minor versions). Key differentiators include deep integration with the OCI ecosystem, comprehensive TypeScript type definitions for robust development, and consistent API patterns across all OCI services supported by the SDK.","status":"active","version":"2.124.0","language":"javascript","source_language":"en","source_url":"https://github.com/oracle/oci-typescript-sdk","tags":["javascript","typescript"],"install":[{"cmd":"npm install oci-globallydistributeddatabase","lang":"bash","label":"npm"},{"cmd":"yarn add oci-globallydistributeddatabase","lang":"bash","label":"yarn"},{"cmd":"pnpm add oci-globallydistributeddatabase","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary client class for interacting with the Globally Distributed Database service. CommonJS `require` is not the idiomatic way for newer OCI SDK versions.","wrong":"const GloballyDistributedDatabaseClient = require('oci-globallydistributeddatabase');","symbol":"GloballyDistributedDatabaseClient","correct":"import { GloballyDistributedDatabaseClient } from 'oci-globallydistributeddatabase';"},{"note":"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.","wrong":"import { Auth } from 'oci-globallydistributeddatabase';","symbol":"Auth","correct":"import * as common from 'oci-common';\nconst provider = new common.Auth.ConfigFileAuthenticationDetailsProvider();"},{"note":"Request and response types are nested under their respective service namespaces (e.g., `GloballyDistributedDatabaseRequests`, `GloballyDistributedDatabaseResponses`) for better organization and to prevent naming conflicts.","wrong":"import { ListShardedDatabasesRequest } from 'oci-globallydistributeddatabase/lib/globallydistributeddatabase_request';","symbol":"ListShardedDatabasesRequest","correct":"import { GloballyDistributedDatabaseRequests } from 'oci-globallydistributeddatabase';\nconst request: GloballyDistributedDatabaseRequests.ListShardedDatabasesRequest = {};"}],"quickstart":{"code":"import { GloballyDistributedDatabaseClient } from 'oci-globallydistributeddatabase';\nimport * as common from 'oci-common';\nimport { GloballyDistributedDatabaseRequests } from 'oci-globallydistributeddatabase';\n\nasync function listGloballyDistributedDatabases() {\n  try {\n    // Configure authentication using a config file (typically ~/.oci/config)\n    // Ensure your OCI config file is set up with a profile.\n    const provider = new common.Auth.ConfigFileAuthenticationDetailsProvider();\n\n    // Initialize the client\n    const client = new GloballyDistributedDatabaseClient({ authenticationDetailsProvider: provider });\n\n    // Construct a list request. A compartmentId is typically required for listing resources.\n    // Replace 'ocid1.compartment.oc1..aaaa...' with your actual compartment OCID.\n    const compartmentId = process.env.OCI_COMPARTMENT_ID ?? 'ocid1.compartment.oc1..examplecompartmentid'; \n    \n    const listRequest: GloballyDistributedDatabaseRequests.ListShardedDatabasesRequest = {\n      compartmentId: compartmentId,\n      limit: 10 // Optional: limit the number of results\n    };\n\n    // Make the API call to list sharded databases\n    console.log(`Listing sharded databases in compartment: ${compartmentId}...`);\n    const response = await client.listShardedDatabases(listRequest);\n\n    // Process the response\n    if (response.shardedDatabaseCollection?.items && response.shardedDatabaseCollection.items.length > 0) {\n      console.log('Found Sharded Databases:');\n      response.shardedDatabaseCollection.items.forEach(db => {\n        console.log(`- Name: ${db.displayName}, ID: ${db.id}, Lifecycle State: ${db.lifecycleState}`);\n      });\n    } else {\n      console.log('No sharded databases found in the specified compartment.');\n    }\n  } catch (error) {\n    console.error('Error listing sharded databases:', error);\n    // Log specific OCI errors for better debugging\n    if (error instanceof common.Error.ServiceError) {\n      console.error(`OCI Service Error: ${error.statusCode} - ${error.serviceCode} (${error.errorCode}): ${error.message}`);\n    }\n    process.exit(1);\n  }\n}\n\nlistGloballyDistributedDatabases();\n","lang":"typescript","description":"This quickstart demonstrates how to instantiate the `GloballyDistributedDatabaseClient`, configure authentication using the OCI config file, and list sharded databases within a specified OCI compartment."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","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":"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.","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.","error":"NotAuthorizedOrNotFound"},{"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\"`).","cause":"The package is not installed or the import path is incorrect, especially in projects mixing ESM and CJS modules.","error":"Error: Cannot find module 'oci-globallydistributeddatabase'"},{"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.","cause":"The `listShardedDatabases` method or the `GloballyDistributedDatabaseClient` object might be incorrectly instantiated or imported.","error":"TypeError: client.listShardedDatabases is not a function"}],"ecosystem":"npm"}