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.
DatabaseManagementClient
✓ import { DatabaseManagementClient } from 'oci-databasemanagement';
✗ const DatabaseManagementClient = require('oci-databasemanagement').DatabaseManagementClient;
Primary client class for interacting with the Database Management service. Prefer ES Modules (ESM) `import` syntax.
models
✓ import * as models from 'oci-databasemanagement/lib/model';
Contains all request, response, and data structure interfaces. Access specific types like `models.ListManagedDatabasesRequest`.
common
✓ import * as common from 'oci-common';
✗ import { ConfigFileAuthenticationDetailsProvider } from 'oci-databasemanagement';
Provides core OCI functionalities, including authentication providers and region handling. Required for client setup.
Auth
✓ import { Auth } from 'oci-common';
Type definition for authentication details providers. Useful for type-checking when creating custom auth providers or using built-in ones like `ConfigFileAuthenticationDetailsProvider`.
Demonstrates how to initialize the OCI Database Management client using various authentication methods and list managed databases within a specified compartment and region.
import { DatabaseManagementClient } from 'oci-databasemanagement';
import * as common from 'oci-common';
import * as models from 'oci-databasemanagement/lib/model'; // Correct path for models
async function listManagedDatabasesExample() {
// Ensure these environment variables are set or replace with actual values
const COMPARTMENT_OCID = process.env.OCI_COMPARTMENT_OCID ?? 'ocid1.compartment.oc1..examplecompartmentid';
const REGION = process.env.OCI_REGION ?? 'us-ashburn-1'; // e.g., 'us-phoenix-1'
// Configure authentication using a config file (~/.oci/config)
// and a specific profile (e.g., 'DEFAULT') or pass a ConfigFileAuthenticationDetailsProvider instance.
let provider: common.Auth.AuthenticationDetailsProvider;
try {
provider = new common.ConfigFileAuthenticationDetailsProvider();
// Set the region from the provider's config or explicitly
common.Region.set(provider.getRegion());
} catch (error) {
console.warn("Could not load OCI config file, attempting instance principal or resource principal authentication.");
// Fallback to instance principal or resource principal if config file fails
provider = new common.InstancePrincipalAuthenticationDetailsProvider();
common.Region.set(REGION); // Explicitly set region for instance principal
}
const client = new DatabaseManagementClient({ authenticationDetailsProvider: provider });
// You can also explicitly set the region if not derived from provider or for overriding
client.region = REGION;
try {
const listManagedDatabasesRequest: models.ListManagedDatabasesRequest = {
compartmentId: COMPARTMENT_OCID,
limit: 10,
};
console.log(`Listing managed databases in compartment: ${COMPARTMENT_OCID} in region: ${client.region}...`);
const response = await client.listManagedDatabases(listManagedDatabasesRequest);
if (response.managedDatabaseCollection.items.length > 0) {
console.log(`Found ${response.managedDatabaseCollection.items.length} managed databases:`);
response.managedDatabaseCollection.items.forEach(db => {
console.log(` - Name: ${db.name}, ID: ${db.id}, Status: ${db.lifecycleState}`);
});
} else {
console.log('No managed databases found in this compartment.');
}
} catch (error) {
console.error('Error listing managed databases:', error);
if (error instanceof common.ServiceError) {
console.error(`OCI Service Error: ${error.statusCode} - ${error.serviceCode} - ${error.message}`);
}
}
}
listManagedDatabasesExample();
Debug
Known issues
gotchaIncorrect or missing OCI configuration file (~/.oci/config), misconfigured environment variables (OCI_CONFIG_FILE_PATH, OCI_PROFILE), or invalid API key details are the most common source of `NotAuthenticated` errors. Ensure the `authenticationDetailsProvider` is correctly instantiated.fixVerify your `~/.oci/config` file exists, is readable, and contains a valid profile. Ensure the private key file path is correct and accessible. For instance principal, ensure the code is running on an OCI instance with the correct IAM policies.
affects: >=1.0.0
gotchaThe client's configured region must match the region where the target resources exist. Mismatched regions can lead to `NotAuthorizedOrNotFound` errors or `Hostname not found` errors, as the SDK attempts to connect to an incorrect endpoint.fixExplicitly set the client region (e.g., `client.region = 'us-ashburn-1'`) or ensure your authentication provider is configured with the correct region. Environment variable `OCI_REGION` can also be used with `ConfigFileAuthenticationDetailsProvider`.
affects: >=1.0.0
breakingEven with correct authentication, operations will fail with `NotAuthorizedOrNotFound` if the OCI user or instance principal lacks the necessary IAM policies to perform actions on the target resources in the specified compartment.fixReview OCI IAM policies for the user/group or instance principal. Ensure policies grant `manage` or `read` permissions for `database-management-family` or specific `database-management-` resource types in the relevant compartment.
affects: >=1.0.0
gotchaOlder Node.js projects using CommonJS `require()` might encounter issues with the OCI SDK, which is primarily designed for ES Modules (`import`). Using `require('oci-databasemanagement').DatabaseManagementClient` might lead to unexpected behavior or `TypeError: ... is not a constructor`.fixFor new projects, use ES Modules (`"type": "module"` in `package.json` and `import` syntax). For CommonJS projects, explicitly access the default export or ensure compatible import patterns. The preferred method is to use ESM.
affects: >=2.0.0
breakingWhile minor releases are additive, major version updates (e.g., `v1` to `v2`) of the OCI SDK can introduce significant breaking changes, including API method signature alterations, model property renames, or complete refactoring of client classes.fixAlways consult the official OCI TypeScript SDK release notes and migration guides before upgrading to a new major version. Test thoroughly.
affects: Check specific major version release notes.
Errors
Common errors & fixes
ServiceError: NotAuthenticated. The required information to complete authentication was not supplied.
Missing or invalid API key, config file, or authentication provider setup.
fixEnsure `~/.oci/config` is correctly configured, including private key path. Verify environment variables for API key auth or correct instance principal setup.
ServiceError: NotAuthorizedOrNotFound. Authorization failed or requested resource not found.
Insufficient IAM permissions for the principal making the request, or the resource OCID/name is incorrect/doesn't exist in the specified compartment/region.
fixCheck OCI IAM policies for the user/group or instance principal. Verify the resource OCID and compartment OCID. Confirm the client's region matches the resource's region.
getaddrinfo ENOTFOUND <service-endpoint>.region.oraclecloud.com
Incorrect region specified, or a network connectivity issue preventing DNS resolution of the OCI service endpoint.
fixDouble-check the region string (e.g., `us-ashburn-1`, not `ashburn`). Ensure your network allows outbound connections to OCI endpoints.
TypeError: DatabaseManagementClient is not a constructor
CommonJS `require()` syntax used in an environment primarily expecting ES Modules, or incorrect access to the exported class.
fixIf using ES Modules, use `import { DatabaseManagementClient } from 'oci-databasemanagement';`. If forced to use CommonJS, use `const { DatabaseManagementClient } = require('oci-databasemanagement');` or `const DatabaseManagementClient = require('oci-databasemanagement').DatabaseManagementClient;`, though ESM is preferred. ServiceError: InvalidParameter. compartmentId is required.
A required parameter for an API operation (e.g., `compartmentId` for listing resources) was omitted or passed as `undefined`.
fixReview the API documentation for the specific request object (e.g., `ListManagedDatabasesRequest`) and ensure all `required` properties are provided with valid values.
Audit
Dependencies
oci-commonrequiredProvides fundamental utilities for OCI SDKs, including authentication providers (e.g., ConfigFileAuthenticationDetailsProvider), region management, error handling, and core HTTP request functionalities.