OCI Database Tools Service Client for NodeJS

Common errors

• ServiceError: NotAuthenticated. The request must be signed with a valid authentication credential to use the API.

  cause The SDK could not find or validate authentication credentials (API Key or Instance Principal).
  fix Verify `~/.oci/config` file contents, permissions (private key must be `0400`), and environment variables (e.g., `OCI_CONFIG_FILE`, `OCI_PROFILE`). Ensure the public key is uploaded to the OCI user API Keys.

• ServiceError: NotFound. The specified resource does not exist.

  cause An OCID provided in the request (e.g., for a compartment or specific database tool connection) is incorrect or refers to a deleted resource.
  fix Check the exact OCID(s) in your request parameters against the OCI Console or `oci-cli` to confirm they are valid and refer to existing resources in the correct region and tenancy.

• ServiceError: BadArgument. One or more parameters in the request were invalid.

  cause A required parameter for an API operation was missing, or a provided parameter had an invalid format or value.
  fix Consult the OCI API documentation for the specific operation to ensure all required fields are present and their values adhere to the specified constraints (e.g., data types, enum values, length limits).

Warnings

• gotcha OCI SDKs require proper authentication configuration via `~/.oci/config` file or environment variables (`OCI_CONFIG_FILE`, `OCI_PROFILE`, `OCI_REGION`, etc.). Incorrect setup often leads to `NotAuthenticated` errors.
  Fix: Ensure your `~/.oci/config` file is correctly configured with your user OCID, tenancy OCID, fingerprint, and private key path. Alternatively, set environment variables like `OCI_TENANCY`, `OCI_USER`, `OCI_FINGERPRINT`, `OCI_KEY_FILE`, and `OCI_REGION`.
• gotcha The SDK relies heavily on Oracle Cloud Identifiers (OCIDs) for resources. Providing an incorrect or non-existent OCID for compartments or resources will result in `NotFound` errors, even if authentication is successful.
  Fix: Double-check all OCIDs used in your requests for correctness. Use the OCI Console or `oci-cli` to verify resource OCIDs before incorporating them into your code.
• gotcha By default, the SDK determines the region from your OCI configuration. If running in an environment without a configured region (e.g., local development without `~/.oci/config`) or if you need to override the configured region, explicit region setting is required.
  Fix: Set the `OCI_REGION` environment variable or explicitly provide the region when creating the authentication provider: `const provider = new common.DefaultAuthenticationDetailsProvider({ region: 'us-ashburn-1' });`

Install

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

Imports

• DatabaseToolsClient
  wrong:

  const DatabaseToolsClient = require('oci-databasetools').DatabaseToolsClient;

  correct:

  import { DatabaseToolsClient } from 'oci-databasetools';

  The OCI TypeScript SDK is primarily designed for ES Modules. While CommonJS might work in some setups, direct ES module imports are recommended, especially for TypeScript projects.
• models

  import * as models from 'oci-databasetools/lib/model';

  Types for requests and responses are typically found under the 'lib/model' sub-path. This import pattern ensures you get all necessary types for the service.
• common
  wrong:

  import { DefaultAuthenticationDetailsProvider } from 'oci-databasetools';

  correct:

  import * as common from 'oci-common';

  Authentication and other core utilities like the `DefaultAuthenticationDetailsProvider` are provided by the separate `oci-common` package, not directly from the service client package itself.

Quickstart

This quickstart initializes the OCI Database Tools client using default authentication, then lists active database tools connections within a specified compartment. It demonstrates basic client instantiation, request creation, and error handling.

import * as common from 'oci-common';
import * as databasetools from 'oci-databasetools';
import * as models from 'oci-databasetools/lib/model';

async function main() {
  try {
    // Configure authentication provider. This will attempt to load configuration
    // from ~/.oci/config (recommended) or environment variables.
    const provider = new common.DefaultAuthenticationDetailsProvider();

    // Create a client for the Database Tools Service
    const client = new databasetools.DatabaseToolsClient({
      authenticationDetailsProvider: provider
    });

    // Replace with your compartment ID (e.g., from environment variable or direct string)
    const compartmentId = process.env.OCI_COMPARTMENT_ID ?? 'ocid1.compartment.oc1..exampleuniqueid';

    console.log(`Listing Database Tools Connections in compartment: ${compartmentId}`);

    const listConnectionsRequest: models.ListDatabaseToolsConnectionsRequest = {
      compartmentId: compartmentId,
      limit: 10, // Limit results for demonstration
      lifecycleState: models.DatabaseToolsConnection.LifecycleState.Active // Filter for active connections
    };

    const response = await client.listDatabaseToolsConnections(listConnectionsRequest);

    if (response.databaseToolsConnectionCollection.items.length > 0) {
      console.log('Found Database Tools Connections:');
      response.databaseToolsConnectionCollection.items.forEach(connection => {
        console.log(`- ${connection.displayName} (ID: ${connection.id}, State: ${connection.lifecycleState})`);
      });
    } else {
      console.log('No active Database Tools Connections found in this compartment.');
    }

  } catch (error) {
    console.error('Error interacting with OCI Database Tools Service:', error);
    if (error instanceof common.errors.ServiceError) {
      console.error(`OCI Service Error: ${error.statusCode} - ${error.serviceCode}`);
      console.error(`Message: ${error.message}`);
    } else if (error instanceof Error) {
      console.error(`General Error: ${error.message}`);
    }
  }
}

main();