OCI Node.js Client for Database Management Service

Common errors

• ServiceError: NotAuthenticated. The required information to complete authentication was not supplied.

  cause Missing or invalid API key, config file, or authentication provider setup.
  fix Ensure `~/.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.

  cause Insufficient IAM permissions for the principal making the request, or the resource OCID/name is incorrect/doesn't exist in the specified compartment/region.
  fix Check 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

  cause Incorrect region specified, or a network connectivity issue preventing DNS resolution of the OCI service endpoint.
  fix Double-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

  cause CommonJS `require()` syntax used in an environment primarily expecting ES Modules, or incorrect access to the exported class.
  fix If 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.

  cause A required parameter for an API operation (e.g., `compartmentId` for listing resources) was omitted or passed as `undefined`.
  fix Review the API documentation for the specific request object (e.g., `ListManagedDatabasesRequest`) and ensure all `required` properties are provided with valid values.

Warnings

• gotcha Incorrect 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.
  Fix: Verify 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.
• gotcha The 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.
  Fix: Explicitly 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`.
• breaking Even 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.
  Fix: Review 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.
• gotcha Older 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`.
  Fix: For 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.
• breaking While 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.
  Fix: Always consult the official OCI TypeScript SDK release notes and migration guides before upgrading to a new major version. Test thoroughly.

Install

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

Imports

• DatabaseManagementClient
  wrong:

  const DatabaseManagementClient = require('oci-databasemanagement').DatabaseManagementClient;

  correct:

  import { DatabaseManagementClient } from 'oci-databasemanagement';

  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
  wrong:

  import { ConfigFileAuthenticationDetailsProvider } from 'oci-databasemanagement';

  correct:

  import * as common from 'oci-common';

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

Quickstart

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();