{"id":16465,"library":"oci-databasemigration","title":"OCI Database Migration Service Client for Node.js","description":"The `oci-databasemigration` package provides a Node.js client for interacting with the Oracle Cloud Infrastructure (OCI) Database Migration Service. It allows developers to programmatically manage resources related to database migrations within the OCI ecosystem, such as creating, managing, and monitoring migration jobs. This module is an integral part of the broader OCI TypeScript SDK and ships with comprehensive TypeScript type definitions, enabling robust development with full type safety. As of version 2.130.0, the SDK is actively maintained, with a rapid release cadence (typically multiple minor versions per month, as evidenced by recent release logs) that consistently introduces support for new OCI services, features, and API endpoints across various OCI components, not solely Database Migration. Its key differentiator is being the official, idiomatic client for OCI services, ensuring seamless compatibility and strict alignment with OCI's continuously evolving API landscape. Successful usage requires an existing OCI account, a configured user with appropriate IAM policies, and an API signing key pair for authentication.","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-databasemigration","lang":"bash","label":"npm"},{"cmd":"yarn add oci-databasemigration","lang":"bash","label":"yarn"},{"cmd":"pnpm add oci-databasemigration","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"OCI SDKs typically export modules as namespaces, requiring `import * as service from 'oci-servicename';` and then accessing `service.ServiceClient`. Direct named imports are generally not supported for client classes.","wrong":"import { DatabaseMigrationClient } from 'oci-databasemigration';","symbol":"DatabaseMigrationClient","correct":"import * as databasemigration from 'oci-databasemigration';\nconst client = new databasemigration.DatabaseMigrationClient({...});"},{"note":"Authentication details providers are part of the `oci-common` package, not service-specific packages. Ensure `oci-common` is also installed.","wrong":"import { ConfigFileAuthenticationDetailsProvider } from 'oci-databasemigration';","symbol":"common.ConfigFileAuthenticationDetailsProvider","correct":"import * as common from 'oci-common';\nconst provider = new common.ConfigFileAuthenticationDetailsProvider();"},{"note":"Request and response types are nested under the service namespace's `requests` and `responses` sub-namespaces respectively.","wrong":"import { ListMigrationsRequest } from 'oci-databasemigration/lib/request';","symbol":"requests.ListMigrationsRequest","correct":"import * as databasemigration from 'oci-databasemigration';\nconst request: databasemigration.requests.ListMigrationsRequest = { compartmentId: '...' };"}],"quickstart":{"code":"import * as databasemigration from 'oci-databasemigration';\nimport * as common from 'oci-common';\n\n// IMPORTANT: Ensure your OCI configuration file (typically ~/.oci/config) is set up\n// and the profile is configured for API signing keys.\n// You can also pass authentication details directly, but a config file is common.\n// For sensitive keys, use environment variables or OCI Vault.\n// Example environment variables for authentication (not recommended for production keys):\n// process.env.OCI_COMPARTMENT_ID\n// process.env.OCI_USER_OCID\n// process.env.OCI_TENANCY_OCID\n// process.env.OCI_FINGERPRINT\n// process.env.OCI_PRIVATE_KEY_PATH\n// process.env.OCI_REGION\n\nasync function listOciDatabaseMigrations() {\n  try {\n    // Initialize the authentication provider using the default OCI config file and profile\n    const authProvider = new common.ConfigFileAuthenticationDetailsProvider();\n\n    // Create a client for the Database Migration Service\n    const client = new databasemigration.DatabaseMigrationClient({\n      authenticationDetailsProvider: authProvider,\n      region: authProvider.getRegion() // Use region from config or explicitly set\n    });\n\n    // Define the compartment ID where your migrations are located\n    const compartmentId = process.env.OCI_COMPARTMENT_ID || 'ocid1.compartment.oc1..examplecompartmentid'; \n    if (compartmentId === 'ocid1.compartment.oc1..examplecompartmentid') {\n      console.warn('Using a placeholder compartment ID. Please set OCI_COMPARTMENT_ID environment variable or replace it directly.');\n    }\n\n    // Create a request object to list migrations in the specified compartment\n    const listMigrationsRequest: databasemigration.requests.ListMigrationsRequest = {\n      compartmentId: compartmentId,\n      lifecycleState: databasemigration.models.Migration.LifecycleState.Active // Optional: Filter by active migrations\n    };\n\n    console.log(`Listing OCI Database Migrations in compartment: ${compartmentId}...`);\n\n    // Call the API to list migrations\n    const response = await client.listMigrations(listMigrationsRequest);\n\n    if (response.items && response.items.length > 0) {\n      console.log(`Found ${response.items.length} migrations:`)\n      response.items.forEach(migration => {\n        console.log(`- ${migration.displayName} (OCID: ${migration.id}, State: ${migration.lifecycleState})`);\n      });\n    } else {\n      console.log('No database migrations found in the specified compartment.');\n    }\n  } catch (error) {\n    console.error('Error listing OCI Database Migrations:', error);\n    if (error instanceof Error && error.message.includes('AuthNFailed')) {\n        console.error('Authentication failed. Please check your OCI config file and API key setup.');\n    } else if (error instanceof Error && error.message.includes('NotFound')) {\n        console.error('Resource not found. Check compartment ID and permissions.');\n    }\n  }\n}\n\nlistOciDatabaseMigrations();","lang":"typescript","description":"This quickstart demonstrates how to initialize the OCI Database Migration client and list existing migrations within a specified OCI compartment, using credentials from the default OCI config file."},"warnings":[{"fix":"Refer to the OCI documentation on 'Configuring the SDK' (https://docs.cloud.oracle.com/en-us/iaas/Content/API/SDKDocs/typescriptsdkgettingstarted.htm#Configure) to ensure your `~/.oci/config` file, profile, and API key are correctly set up and permissions are granted in OCI IAM.","message":"OCI SDKs heavily rely on a local configuration file (`~/.oci/config`) and API signing key pairs for authentication. Misconfiguration of this file or incorrect key pair setup is the most common cause of authentication failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `oci-common` is installed and up-to-date (`npm install oci-common`). When importing shared utilities, always use `import * as common from 'oci-common';`.","message":"The `oci-databasemigration` package is a service-specific module. For full functionality, it depends on `oci-common` for shared utilities like authentication providers, retry mechanisms, and general OCI types. While `npm install oci-databasemigration` should pull `oci-common` as a dependency, explicitly understanding this relationship is crucial for debugging.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure the `region` parameter in the client constructor matches the region where your OCI resources are deployed. You can retrieve it from `authProvider.getRegion()` if using `ConfigFileAuthenticationDetailsProvider` or explicitly pass the region string (e.g., `'us-ashburn-1'`).","message":"OCI SDKs typically expect region to be explicitly set in the client configuration, or derived from the `authenticationDetailsProvider`. Using a mismatched region or an invalid region can lead to 'Not Found' or 'Unauthorized' errors, or even silent failures if the API endpoint doesn't exist in that region.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Subscribe to OCI SDK release notes and review the changelog on GitHub for any breaking changes when upgrading major versions or encountering unexpected behavior after an upgrade. Test critical paths in a staging environment before deploying to production.","message":"While no specific breaking changes were noted in the provided recent release logs, the OCI SDKs follow the general API versioning of OCI services. Major breaking changes are typically communicated through explicit version bumps in the service-specific modules. Developers should review release notes for significant version updates.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify all details in your `~/.oci/config` file. Ensure the private key file exists at the specified path and has correct permissions. Confirm the public key for the fingerprint is uploaded to your OCI user's API Keys.","cause":"Incorrect OCI configuration file (`~/.oci/config`), invalid API key fingerprint, private key path mismatch, or incorrect user/tenancy OCIDs.","error":"Error: AuthNFailed - The client could not be authenticated."},{"fix":"Check OCI IAM policies for the user and group. Ensure the policy grants `manage databasemigration-family` or specific verbs/resources within the compartment. Also, double-check the OCID of the resource and compartment.","cause":"The OCI user attempting the API call lacks the necessary IAM permissions for the resource or action, or the resource does not exist in the specified compartment/region for that user.","error":"Error: 401 Unauthorized or 404 Not Found (specific resource, but general auth/permission issue)"},{"fix":"Change `import { DatabaseMigrationClient } from 'oci-databasemigration';` to `import * as databasemigration from 'oci-databasemigration';` and then use `new databasemigration.DatabaseMigrationClient({...});`.","cause":"Incorrect import statement. The client class is not directly exported but accessed via the `databasemigration` namespace.","error":"TypeError: Cannot read properties of undefined (reading 'DatabaseMigrationClient')"},{"fix":"Correct the region name. Ensure it matches one of the valid regions listed in the error message or the OCI documentation for the service. For `ConfigFileAuthenticationDetailsProvider`, check the `region` setting in `~/.oci/config`.","cause":"The specified OCI region in the client configuration or environment is misspelled, unsupported, or incorrect for the OCI realm.","error":"Error: Region 'us-phoenix-1' is not a valid region. Valid regions are: ..."}],"ecosystem":"npm"}