Azure Cosmos DB for MongoDB Setup Guide

Follow these instructions to connect your Azure Cosmos DB for MongoDB database to your destination using Fivetran.

NOTE: We only support Request Unit (RU)-based Azure Cosmos DB for MongoDB accounts with version 3.6 and above.

Setup instructions

Choose connection method

Decide whether to connect Fivetran to your Azure Cosmos DB for MongoDB database directly or using a private link.

Find host identifiers

1. In the Microsoft Azure Portal, navigate to the Azure Cosmos DB for MongoDB database you want to replicate.

2. On the left navigation menu, select Connection strings.

3. Go to the Read-only Keys tab and copy the PRIMARY CONNECTION STRING.

NOTE:

• Optionally, you can specify the read preference in the connection string based on your priority, for example, mongodb://<host-name>:<port>/?readPreference=secondary.

  Read Preference	Priority
  secondaryPreferred(default)	Optimal performance
  primaryPreferred or secondaryPreferred	High availability
  nearest	Optimal performance for geographically distributed data

• If you use the primary/primaryPreferred read preference, it may affect the operational performance of your database.

Allow database access

1. In the Microsoft Azure Portal, on the top right panel, click Cloud Shell to open the Azure Command-Line Interface (CLI).

   TIP: Alternatively, you can download the Azure CLI from the How to install the Azure CLI page.

2. Enable the Role-Based Access Control (RBAC) capability on your existing API for the Azure Cosmos DB for MongoDB account by running the following command:

   az cosmosdb create -n <account_name> -g <azure_resource_group> --kind MongoDB --capabilities EnableMongoRoleBasedAccessControl
   

   TIP: Alternatively, RBAC can also be enabled through the features tab in the Azure portal.

3. Create a role definition for the new Fivetran user you want to create by running the following command:

   az cosmosdb mongodb user definition create --account-name <account-name> --resource-group <resource-group-name> --body '{
      "Id": "<authentication-database-name>.<fivetran-user>",
      "UserName": "<fivetran-user>",
      "Password": "<password>",
      "DatabaseName": "<authentication-database-name>",
      "CustomData": "Some_Random_Info",
      "Mechanisms": "SCRAM-SHA-256",
      "Roles": [{
            "Role": "read",
            "Db": "<authentication-database-name>"
      }]
   }'
   

Additionally, you must grant read permissions to the Fivetran user for each database you want to sync. Do the following:

1. Open the Azure Command-Line Interface (CLI).

2. Run the following command for each database that you want to sync:

 az cosmosdb mongodb user definition create --account-name <account-name> --resource-group <resource-group-name> --body '{
    "Id": "<your-database-name>.<fivetran-user>",
    "UserName": "<fivetran-user>",
    "Password": "<password>",
    "DatabaseName": "<your-database-name>",
    "CustomData": "Some_Random_Info",
    "Mechanisms": "SCRAM-SHA-256",
    "Roles": [{
           "Role": "read",
           "Db": "<your-database-name>"
    }]
 }'

NOTE: Provide the same username and password you used for the Fivetran user.

For more information, see Azure Cosmos DB for MongoDB's Configuring RBAC documentation.

Finish Fivetran configuration

1. In your connector setup form, enter a Destination schema prefix. This prefix applies to each replicated schema and cannot be changed once your connector is created.

2. In the Host and ports field, enter the host identifiers you found in Step 2.

3. Enter the Fivetran-specific User and its Password that you created in Step 3.

4. Enter the source database name to be used for authentication. The user must have access to read from this database.

5. Choose your Connection Method.

6. Select your Pack mode.

7. Click Save & Test. Fivetran tests and validates our connection to your Azure Cosmos DB for MongoDB deployment. Upon successful completion of the setup tests, you can sync your data using Fivetran.

Setup tests

Fivetran performs the following tests to ensure that we can connect to your Azure Cosmos DB for MongoDB deployment and that it is properly configured:

• The Validate Host Test validates the database credentials you provided in the setup form. It then verifies that the database host is not private and checks that we can connect to the host.
• The Validating Certificate Test generates a pop-up window where you must choose which certificate you want Fivetran to use. Select the root certificate to trust all the configured hosts. It then validates that certificate and checks that we can connect to your database using TLS.
• The Connecting to Host Test connects to your database instance and checks if we can access the schemas in your database.
• The Database Access Test verifies if we have the permissions to query at least one collection.
• The Change Stream Access Test checks if we can access the collection level change streams.

NOTE: The tests may take a few minutes to finish running.

Related articles

description Connector Overview

account_tree Schema Information

assignment API Connector Configuration

assignment Release Notes

home Documentation Home