Link Cosmos DB Integration

Introduction

The purpose of this document is to guide on integrating your web application with Azure Cosmos DB for MongoDB. By following the steps outlined herein, you will seamlessly incorporate Cosmos DB into your application's data storage and retrieval processes. This document aims to:
  • Offer a clear and systematic approach to integrating your web application with Cosmos DB alongside MongoDB as the primary database.
  • Provide troubleshooting tips and solutions for common integration challenges.
  • Allow switching between MongoDB and Cosmos DB by making changes in the config.yaml configuration file.

Audience

This document is designed to serve various audiences of professionals involved in the integration and management of a web application utilizing Azure Cosmos DB for MongoDB along with existing MongoDB in Link.

Prerequisites

Ensure that these prerequisites are met before integrating your web application with Azure Cosmos DB for MongoDB:
  • Access Credentials: Obtain valid access credentials for Azure Cosmos DB and MongoDB instances.
  • Link Framework: Ensure your web application is built on the Link framework.
  • Configuration Details: Have the necessary configuration details, including Cosmos DB URI and relevant settings.

Overview of Integration

The Link Cosmos DB Integration is a strategic enhancement for web applications utilizing Azure Cosmos DB for MongoDB in conjunction with existing MongoDB setups. This integration seamlessly integrates Cosmos DB, offering a systematic approach to data storage and retrieval processes within your web application. By enabling the coexistence of MongoDB and Cosmos DB, this integration ensures flexibility and scalability in managing diverse data requirements. Here are the following benefits:
  • Flexibility in Database Selection: The integration provides the flexibility to choose between MongoDB and Cosmos DB, allowing developers to leverage the strengths of each database for specific use cases without major code modifications.
  • Seamless Transition: With changes made in the config.yaml file, transitioning between MongoDB and Cosmos DB is a straightforward process. This ensures minimal disruption to existing workflows during database configuration changes.
  • Enhanced Query Performance: Optimizations in index configurations and parameter adjustments contribute to improved query performance, ensuring that data retrieval processes are efficient, regardless of the underlying database technology.
  • Compatibility Assurance: The integration undergoes meticulous unit and integration testing, ensuring that existing functionalities within Link remain consistent across MongoDB and Cosmos DB. This compatibility assurance minimizes the risk of unforeseen issues during and after the integration process.
  • Scalability and Future-Readiness: Link CosmosDB Integration is designed to scale with the evolving needs of your web application. Whether accommodating growing data volumes or adapting to changes in database technology, this integration provides a robust foundation for future growth.

Key Features

Here are the key features:
  • Unified Database Support: Link CosmosDB Integration facilitates the simultaneous use of MongoDB and Cosmos DB within the Link framework. This means your application can seamlessly switch between these databases based on specific needs, providing a unified approach to data management.
  • Metadata Verification: Verifies the install log. This allows applications to dynamically identify and adapt to Cosmos DB, ensuring proper handling of database-specific features and requirements.
  • Optimized Indexing: Adjustments in index configurations.
  • Schema and Chunk Size Customization: This allows schema and chunk size customization.

Compatibility

The Link Cosmos DB Integration is designed to work seamlessly within various system and platform environments, ensuring broad compatibility and flexibility in deployment. Here is an overview of the compatibility aspects:
  • Operating Systems: The integration is compatible with popular operating systems, such as:
    • Windows
    • Linux
  • Web Browsers: The web applications utilizing Link Cosmos DB Integration are compatible with standard web browsers, such as:
    • Microsoft Edge
    • Google Chrome
    • Mozilla Firefox

Configuration Details

These are the following configuration details for successfully configuring the Link Cosmos DB Integration:
  • Update the value of cosmosDBUri to the URI of your Azure Cosmos DB for MongoDB in the config.yaml file if the customer is using cosmosDB, otherwise keep the existing MongoDB setting.
    Note: Link is already using MongoDB and mongoClient supports CosmosDB, so no change is required in existing jars.
  • Updated Link Hip-Server build to integrate MongoDB and cosmosDB:
    • _isCosmosDB flag added to verify cosmos DB from metadata.
    • For cosmos indexes on the collections changed from index.hashed to index.ascending as cosmos do not support hashed indexes.
    • The schema.getCurrentTypes is set to 2000 for cosmos while it is 10000 for mongo.
    • The chunk size is set to 2000000(2 Mb) for cosmos as it is 10000000(10 Mb) for Mongo.

Integration Steps

By following these steps, you can successfully integrate Cosmos DB with MongoDB:
  1. Setting Up Cosmos DB: To initiate the integration of Cosmos DB with MongoDB, start by creating a Cosmos DB Account specifically configured for MongoDB.
    • Creating a Cosmos DB Account (Cosmos for MongoDB)
    • Select cosmos for mongo option while creating cosmos account in azure.
      Note: Ensure that the total throughput limit is sufficiently high, with a minimum of 40,000 Request Units per second (RU/s).
  2. Download and Install Link. Refer to online Link documentation for installation procedure.
    Note: To utilize Cosmos DB with Link, if Link is already installed, it is recommended to uninstall the existing installation and then perform a fresh installation. This ensures that the installation process is aligned with the Cosmos DB configuration requirements and helps prevent any potential conflicts or issues that may arise from an existing installation. Follow the uninstallation guidelines provided in the Link documentation before initiating the reinstallation process to ensure a clean and seamless integration with Cosmos DB.
  3. Link Configuration: Configure the database connection settings to establish the link between Cosmos DB and MongoDB.
    • Database Connection Settings: Update the config.yaml file and ensure that the Cosmos DB URI is correctly specified for linking with Cosmos DB.
    • Authentication and Authorization: No changes are required in the authentication and authorization settings.
  4. Data Migration: During the installation of the link, the mdb and rdb_XXXXX databases will be created under Cosmos DB. All predefined collections and documents will be generated, ensuring a seamless migration of existing data.
  5. Restart the Link.
  6. Test and Deployment:Conduct thorough testing of the integration and deploy the integration to the production environment after successful testing.

Known Issue

Refer to the following known issue while using Cosmos DB:
  • Performance Degradation Compared to MongoDB:

    Users may experience performance degradation when using Cosmos DB compared to MongoDB in certain scenarios. This could be attributed to differences in underlying architecture, indexing strategies, or query optimization techniques between the two databases.

  • Credential Entry Discrepancy on Windows Installation:

    During the configuration of Cosmos DB on a Windows installation, users may encounter a discrepancy in the credential entry process. Unlike MongoDB, where users typically enter MongoDB credentials, Cosmos DB may require users to input specific Cosmos DB credentials. This difference in the credential management process could potentially lead to confusion or errors during setup.