{"id":16160,"library":"oci-database","title":"OCI Database Service Client for Node.js","description":"The `oci-database` package provides a Node.js client for interacting with the Oracle Cloud Infrastructure (OCI) Database service. It allows developers to programmatically manage database resources such as Autonomous Databases, DB Systems, and various database operations within OCI. This package is part of the larger OCI TypeScript SDK, offering type-safe access to OCI services. Currently at version 2.130.0, the OCI SDK typically follows a frequent release cadence, often aligning with OCI service updates, leading to multiple minor or patch releases per month. Key differentiators include first-party support from Oracle, comprehensive TypeScript type definitions, and integration with OCI's native authentication mechanisms, providing a robust and official way to automate database management tasks in the OCI ecosystem.","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-database","lang":"bash","label":"npm"},{"cmd":"yarn add oci-database","lang":"bash","label":"yarn"},{"cmd":"pnpm add oci-database","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides core utilities, authentication details providers, and common types required by all OCI service clients.","package":"oci-common","optional":false}],"imports":[{"note":"The primary class for interacting with the OCI Database service. Use named imports for modern TypeScript/ESM projects.","wrong":"const DatabaseClient = require('oci-database').DatabaseClient;","symbol":"DatabaseClient","correct":"import { DatabaseClient } from 'oci-database';"},{"note":"Request and response types are typically nested under `requests` and `responses` namespaces in OCI SDK packages to avoid naming conflicts.","wrong":"import { ListDatabasesRequest } from 'oci-database';","symbol":"ListDatabasesRequest","correct":"import { requests } from 'oci-database';\nconst request: requests.ListDatabasesRequest = {};"},{"note":"Authentication providers are part of the `oci-common` package, not directly from `oci-database`.","wrong":"import { ConfigFileAuthenticationDetailsProvider } from 'oci-database';","symbol":"ConfigFileAuthenticationDetailsProvider","correct":"import { auth } from 'oci-common';\nconst provider = new auth.ConfigFileAuthenticationDetailsProvider();"}],"quickstart":{"code":"import { DatabaseClient, requests } from 'oci-database';\nimport { auth, common } from 'oci-common';\n\nasync function listOciDatabases() {\n  try {\n    // Load authentication details from the default OCI config file (~/.oci/config)\n    // Ensure your OCI config file is set up with a profile (e.g., 'DEFAULT') and API key.\n    const provider = new auth.ConfigFileAuthenticationDetailsProvider();\n\n    // The region is typically read from the config file, but can be overridden\n    // For example, common.Region.US_PHOENIX_1\n    const client = new DatabaseClient({ authenticationDetailsProvider: provider });\n\n    // Specify the compartment to list databases from.\n    // Replace 'YOUR_COMPARTMENT_OCID' with an actual Compartment OCID.\n    const compartmentId = process.env.OCI_COMPARTMENT_OCID ?? 'YOUR_COMPARTMENT_OCID';\n    if (compartmentId === 'YOUR_COMPARTMENT_OCID') {\n      console.warn('WARNING: Please set OCI_COMPARTMENT_OCID environment variable or replace placeholder.');\n    }\n\n    const listRequest: requests.ListDatabasesRequest = {\n      compartmentId: compartmentId,\n      // You can add filters like lifecycleState, dbHomeId, etc.\n      // lifecycleState: requests.ListDatabasesRequest.LifecycleState.Available\n    };\n\n    console.log(`Listing databases in compartment: ${compartmentId}...`);\n    const response = await client.listDatabases(listRequest);\n\n    if (response.items && response.items.length > 0) {\n      console.log(`Found ${response.items.length} databases:`)\n      response.items.forEach(db => {\n        console.log(`- ${db.dbName} (OCID: ${db.id}, State: ${db.lifecycleState})`);\n      });\n    } else {\n      console.log('No databases found in the specified compartment.');\n    }\n  } catch (error) {\n    console.error('Error listing databases:', error);\n    if (error instanceof common.ServiceError) {\n      console.error(`Service Error Details: Status=${error.statusCode}, Code=${error.serviceCode}, Message=${error.message}`);\n    }\n  }\n}\n\nlistOciDatabases();","lang":"typescript","description":"This quickstart initializes the `DatabaseClient` using API key authentication from a configuration file and lists all databases within a specified compartment in OCI."},"warnings":[{"fix":"Review OCI IAM documentation for required policies (e.g., `read databases` for listing) and ensure they are assigned to the calling user/group.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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 });`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Incorrect API key setup (missing private key, wrong fingerprint, invalid user OCID) or expired session for instance principal.","error":"ServiceError: 401 Unauthorized. The provided authentication is invalid. Review the setup documentation for API keys or instance principals."},{"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.","cause":"The IAM user or instance principal lacks the necessary permissions to perform the requested operation on the target resource or compartment.","error":"ServiceError: 403 Forbidden. Authorization failed or requested resource not found."},{"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.","cause":"Incorrect import statement (e.g., `require` for ESM-only package) or `DatabaseClient` is not directly exported as a default.","error":"TypeError: DatabaseClient is not a constructor"},{"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.","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.","error":"ServiceError: 404 Not Found. The resource you are trying to access does not exist."}],"ecosystem":"npm"}