OCI Database Service Client for Node.js

Common errors

• ServiceError: 401 Unauthorized. The provided authentication is invalid. Review the setup documentation for API keys or instance principals.

  cause Incorrect API key setup (missing private key, wrong fingerprint, invalid user OCID) or expired session for instance principal.
  fix Verify `~/.oci/config` entries, API key fingerprint, and `private_key_file` path. Ensure your user OCID is correct. For instance principals, check associated dynamic groups and policy permissions.

• ServiceError: 403 Forbidden. Authorization failed or requested resource not found.

  cause The IAM user or instance principal lacks the necessary permissions to perform the requested operation on the target resource or compartment.
  fix Review OCI IAM policies in the OCI Console. Add the required `allow` statements for the user's group or dynamic group to `manage` or `read` the specific resource type (e.g., `databases`) in the target compartment.

• TypeError: DatabaseClient is not a constructor

  cause Incorrect import statement (e.g., `require` for ESM-only package) or `DatabaseClient` is not directly exported as a default.
  fix Ensure you are using ES module imports (`import { DatabaseClient } from 'oci-database';`) in an environment configured for ESM, or if using CommonJS, verify the export structure of the package. It's usually a named export.

• ServiceError: 404 Not Found. The resource you are trying to access does not exist.

  cause The OCID of the resource (e.g., database, compartment) is incorrect, or the client is configured for a different OCI region where the resource does not exist.
  fix Double-check the OCID of the resource you are targeting. Verify that the OCI client's configured region matches the region where the resource resides. OCI OCIDs are globally unique but resources are region-bound.

Warnings

• gotcha OCI SDKs heavily rely on proper IAM policies. Operations will fail with 403 Forbidden errors if the user or instance principal lacks the necessary permissions for the specific API calls. Always verify your OCI IAM policies.
  Fix: Review OCI IAM documentation for required policies (e.g., `read databases` for listing) and ensure they are assigned to the calling user/group.
• gotcha Authentication details (API keys, config file, instance principals) must be correctly configured. Common issues include incorrect file paths, invalid fingerprints, or missing entries in the OCI config file.
  Fix: Refer to the OCI SDK documentation for 'Configuring Credentials'. Ensure `~/.oci/config` is correctly set up with the private key path, fingerprint, and other details. Use environment variables or instance principals where appropriate.
• gotcha Many list operations in OCI SDKs are paginated. If you're expecting more than a single page of results, you must manually implement pagination logic using `opcNextPage` tokens to fetch all items.
  Fix: Implement a loop that repeatedly calls the list operation, passing the `opcNextPage` token from the previous response in the `page` parameter of the subsequent request, until `opcNextPage` is null.
• gotcha The `oci-database` client is region-specific. If the client is initialized for a different region than where your resources reside, operations will often result in 'Not Found' errors (404) or 'Unauthorized' (401) if the region configuration is completely off.
  Fix: Ensure the region configured in your `ConfigFileAuthenticationDetailsProvider` or explicitly set on the client matches the region where your OCI Database resources are located. Example: `new DatabaseClient({ authenticationDetailsProvider: provider, region: common.Region.US_ASHBURN_1 });`

Install

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

Imports

• DatabaseClient
  wrong:

  const DatabaseClient = require('oci-database').DatabaseClient;

  correct:

  import { DatabaseClient } from 'oci-database';

  The primary class for interacting with the OCI Database service. Use named imports for modern TypeScript/ESM projects.
• ListDatabasesRequest
  wrong:

  import { ListDatabasesRequest } from 'oci-database';

  correct:

  import { requests } from 'oci-database';
  const request: requests.ListDatabasesRequest = {};

  Request and response types are typically nested under `requests` and `responses` namespaces in OCI SDK packages to avoid naming conflicts.
• ConfigFileAuthenticationDetailsProvider
  wrong:

  import { ConfigFileAuthenticationDetailsProvider } from 'oci-database';

  correct:

  import { auth } from 'oci-common';
  const provider = new auth.ConfigFileAuthenticationDetailsProvider();

  Authentication providers are part of the `oci-common` package, not directly from `oci-database`.

Quickstart

This quickstart initializes the `DatabaseClient` using API key authentication from a configuration file and lists all databases within a specified compartment in OCI.

import { DatabaseClient, requests } from 'oci-database';
import { auth, common } from 'oci-common';

async function listOciDatabases() {
  try {
    // Load authentication details from the default OCI config file (~/.oci/config)
    // Ensure your OCI config file is set up with a profile (e.g., 'DEFAULT') and API key.
    const provider = new auth.ConfigFileAuthenticationDetailsProvider();

    // The region is typically read from the config file, but can be overridden
    // For example, common.Region.US_PHOENIX_1
    const client = new DatabaseClient({ authenticationDetailsProvider: provider });

    // Specify the compartment to list databases from.
    // Replace 'YOUR_COMPARTMENT_OCID' with an actual Compartment OCID.
    const compartmentId = process.env.OCI_COMPARTMENT_OCID ?? 'YOUR_COMPARTMENT_OCID';
    if (compartmentId === 'YOUR_COMPARTMENT_OCID') {
      console.warn('WARNING: Please set OCI_COMPARTMENT_OCID environment variable or replace placeholder.');
    }

    const listRequest: requests.ListDatabasesRequest = {
      compartmentId: compartmentId,
      // You can add filters like lifecycleState, dbHomeId, etc.
      // lifecycleState: requests.ListDatabasesRequest.LifecycleState.Available
    };

    console.log(`Listing databases in compartment: ${compartmentId}...`);
    const response = await client.listDatabases(listRequest);

    if (response.items && response.items.length > 0) {
      console.log(`Found ${response.items.length} databases:`)
      response.items.forEach(db => {
        console.log(`- ${db.dbName} (OCID: ${db.id}, State: ${db.lifecycleState})`);
      });
    } else {
      console.log('No databases found in the specified compartment.');
    }
  } catch (error) {
    console.error('Error listing databases:', error);
    if (error instanceof common.ServiceError) {
      console.error(`Service Error Details: Status=${error.statusCode}, Code=${error.serviceCode}, Message=${error.message}`);
    }
  }
}

listOciDatabases();