Registry /
database / oci-distributeddatabase
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DistributedDatabaseClient
✓ import { DistributedDatabaseClient } from 'oci-distributeddatabase';
✗ const DistributedDatabaseClient = require('oci-distributeddatabase').DistributedDatabaseClient;
This is the primary client class for interacting with the Distributed Database Service.
models
✓ import * as models from 'oci-distributeddatabase/lib/model';
✗ import { models } from 'oci-distributeddatabase';
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
✓ import { ConfigFileAuthenticationDetailsProvider } from 'oci-common';
✗ import { ConfigFileAuthenticationDetailsProvider } from 'oci-distributeddatabase';
Authentication providers are part of the `oci-common` package, not service-specific packages. Ensure `oci-common` is also installed.
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();
Debug
Known issues
breakingThe 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.fixReview 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.
affects: >=2.0.0
gotchaThe 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.fixBe 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).
affects: >=2.0.0
gotchaThe 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.fixUse 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.
affects: *
gotchaIncorrect 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).fixEnsure 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.
affects: *
gotchaUsing 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.fixEnsure your project's Node.js and TypeScript versions align with the SDK's supported versions to guarantee compatibility and stability.
affects: <2.0.0 (older versions might have different requirements)
Errors
Common errors & fixes
Error: did not find a proper configuration for user
The SDK could not locate or parse the OCI configuration file, or the specified profile is missing/invalid.
fixVerify 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.
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.
fixCheck 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
A network timeout occurred, preventing the SDK from receiving a response from the OCI service within the configured timeout period.
fixIncrease 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')
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.
fixAdd 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`).
Audit
Dependencies
oci-commonrequiredProvides core authentication, request signing, and common utilities for all OCI SDK services.