{"id":16464,"library":"oci-databasemanagement","title":"OCI Node.js Client for Database Management Service","description":"This package provides the official Oracle Cloud Infrastructure (OCI) Node.js client for interacting with the Database Management Service (DMS). It enables developers to programmatically manage and monitor various aspects of Oracle Databases within OCI, including performance diagnostics, SQL tuning, resource utilization, and lifecycle operations. The current stable version is 2.130.0, which is part of the larger OCI TypeScript SDK. The SDK maintains a rapid release cadence, with frequent minor versions released often weekly or bi-weekly, continuously adding support for new OCI services, features, and regions across the entire cloud platform. Its primary differentiators include being the officially supported client from Oracle, guaranteeing compatibility with the latest OCI API specifications, and providing comprehensive TypeScript type definitions for enhanced developer experience. This module is essential for automating database administration tasks and integrating OCI Database Management into custom applications.","status":"active","version":"2.130.0","language":"javascript","source_language":"en","source_url":"https://github.com/oracle/oci-typescript-sdk","tags":["javascript","typescript"],"install":[{"cmd":"npm install oci-databasemanagement","lang":"bash","label":"npm"},{"cmd":"yarn add oci-databasemanagement","lang":"bash","label":"yarn"},{"cmd":"pnpm add oci-databasemanagement","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides fundamental utilities for OCI SDKs, including authentication providers (e.g., ConfigFileAuthenticationDetailsProvider), region management, error handling, and core HTTP request functionalities.","package":"oci-common","optional":false}],"imports":[{"note":"Primary client class for interacting with the Database Management service. Prefer ES Modules (ESM) `import` syntax.","wrong":"const DatabaseManagementClient = require('oci-databasemanagement').DatabaseManagementClient;","symbol":"DatabaseManagementClient","correct":"import { DatabaseManagementClient } from 'oci-databasemanagement';"},{"note":"Contains all request, response, and data structure interfaces. Access specific types like `models.ListManagedDatabasesRequest`.","symbol":"models","correct":"import * as models from 'oci-databasemanagement/lib/model';"},{"note":"Provides core OCI functionalities, including authentication providers and region handling. Required for client setup.","wrong":"import { ConfigFileAuthenticationDetailsProvider } from 'oci-databasemanagement';","symbol":"common","correct":"import * as common from 'oci-common';"},{"note":"Type definition for authentication details providers. Useful for type-checking when creating custom auth providers or using built-in ones like `ConfigFileAuthenticationDetailsProvider`.","symbol":"Auth","correct":"import { Auth } from 'oci-common';"}],"quickstart":{"code":"import { DatabaseManagementClient } from 'oci-databasemanagement';\nimport * as common from 'oci-common';\nimport * as models from 'oci-databasemanagement/lib/model'; // Correct path for models\n\nasync function listManagedDatabasesExample() {\n    // Ensure these environment variables are set or replace with actual values\n    const COMPARTMENT_OCID = process.env.OCI_COMPARTMENT_OCID ?? 'ocid1.compartment.oc1..examplecompartmentid';\n    const REGION = process.env.OCI_REGION ?? 'us-ashburn-1'; // e.g., 'us-phoenix-1'\n\n    // Configure authentication using a config file (~/.oci/config)\n    // and a specific profile (e.g., 'DEFAULT') or pass a ConfigFileAuthenticationDetailsProvider instance.\n    let provider: common.Auth.AuthenticationDetailsProvider;\n    try {\n        provider = new common.ConfigFileAuthenticationDetailsProvider();\n        // Set the region from the provider's config or explicitly\n        common.Region.set(provider.getRegion());\n    } catch (error) {\n        console.warn(\"Could not load OCI config file, attempting instance principal or resource principal authentication.\");\n        // Fallback to instance principal or resource principal if config file fails\n        provider = new common.InstancePrincipalAuthenticationDetailsProvider();\n        common.Region.set(REGION); // Explicitly set region for instance principal\n    }\n\n\n    const client = new DatabaseManagementClient({ authenticationDetailsProvider: provider });\n    // You can also explicitly set the region if not derived from provider or for overriding\n    client.region = REGION;\n\n    try {\n        const listManagedDatabasesRequest: models.ListManagedDatabasesRequest = {\n            compartmentId: COMPARTMENT_OCID,\n            limit: 10,\n        };\n\n        console.log(`Listing managed databases in compartment: ${COMPARTMENT_OCID} in region: ${client.region}...`);\n        const response = await client.listManagedDatabases(listManagedDatabasesRequest);\n\n        if (response.managedDatabaseCollection.items.length > 0) {\n            console.log(`Found ${response.managedDatabaseCollection.items.length} managed databases:`);\n            response.managedDatabaseCollection.items.forEach(db => {\n                console.log(`  - Name: ${db.name}, ID: ${db.id}, Status: ${db.lifecycleState}`);\n            });\n        } else {\n            console.log('No managed databases found in this compartment.');\n        }\n    } catch (error) {\n        console.error('Error listing managed databases:', error);\n        if (error instanceof common.ServiceError) {\n            console.error(`OCI Service Error: ${error.statusCode} - ${error.serviceCode} - ${error.message}`);\n        }\n    }\n}\n\nlistManagedDatabasesExample();","lang":"typescript","description":"Demonstrates how to initialize the OCI Database Management client using various authentication methods and list managed databases within a specified compartment and region."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always consult the official OCI TypeScript SDK release notes and migration guides before upgrading to a new major version. Test thoroughly.","message":"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.","severity":"breaking","affected_versions":"Check specific major version release notes."}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `~/.oci/config` is correctly configured, including private key path. Verify environment variables for API key auth or correct instance principal setup.","cause":"Missing or invalid API key, config file, or authentication provider setup.","error":"ServiceError: NotAuthenticated. The required information to complete authentication was not supplied."},{"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.","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.","error":"ServiceError: NotAuthorizedOrNotFound. Authorization failed or requested resource not found."},{"fix":"Double-check the region string (e.g., `us-ashburn-1`, not `ashburn`). Ensure your network allows outbound connections to OCI endpoints.","cause":"Incorrect region specified, or a network connectivity issue preventing DNS resolution of the OCI service endpoint.","error":"getaddrinfo ENOTFOUND <service-endpoint>.region.oraclecloud.com"},{"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.","cause":"CommonJS `require()` syntax used in an environment primarily expecting ES Modules, or incorrect access to the exported class.","error":"TypeError: DatabaseManagementClient is not a constructor"},{"fix":"Review the API documentation for the specific request object (e.g., `ListManagedDatabasesRequest`) and ensure all `required` properties are provided with valid values.","cause":"A required parameter for an API operation (e.g., `compartmentId` for listing resources) was omitted or passed as `undefined`.","error":"ServiceError: InvalidParameter. compartmentId is required."}],"ecosystem":"npm"}