Prerequisites

• The MongoDB version is 4.0.7 to 8.0.

• You have the Organization Owner, Project Owner, or Project Database Access Admin role in Atlas to create custom roles and database users.

• You have the Project Owner or Project Network Access Manager role in Atlas to edit the IP access list.

• Hevo has permissions to read your MongoDB Atlas databases.

• Hevo’s IP address(es) for your region are added to the MongoDB database IP Allowlist.

• The cluster hostname of your MongoDB Atlas account are available.

---

Set up Permissions to Read MongoDB Atlas Databases

Create a database user for Hevo and grant it read access to the databases you want to replicate. You can grant access through a custom role or assign the roles directly to the user.

Hevo needs the following roles:

• readAnyDatabase on the admin database, or read on each database you want to replicate: To read your collections and their changes.

• clusterMonitor on the admin database: To check your cluster’s configuration and health, such as its replica set status and shards.

1. Create a custom role

Perform the following steps to create a custom role:

1. Log in to the MongoDB Atlas console.

2. In the left navigation pane, under Security, click Database & Network Access.

   

3. On the Database & Network Access page, under DATABASE ACCESS, click Custom Roles.

   

4. Click + ADD NEW CUSTOM ROLE.

   

5. In the Add Custom Role pop-up window, specify the Custom Role Name.

   

6. Assign the required roles:

   

   • Assign either the read role on the database(s) you want to ingest, or the readAnyDatabase role on the admin database.

   • Assign the clusterMonitor role on the admin database.

7. Click Add Custom Role.

2. Create a database user

Perform the following steps to create a database user:

1. Log in to the MongoDB Atlas console.

2. In the left navigation pane, under Security, click Database & Network Access.

   

3. On the Database Users page, click + ADD NEW DATABASE USER.

   

4. In the Add New Database User pop-up window, select Password as the Authentication Method.

   

5. Under Password Authentication, specify the username and password.

   

6. In the Database User Privileges section, do the following:

   • For custom roles created in the previous step:

     1. Click Custom Roles.

        

     2. Click Add Custom Role and select the role that you created above.

        

   • To assign roles directly, without a custom role:

     1. Select Specific Privileges.

        

     2. Click Add Specific Privilege, and do the following:

        

        • Assign either the read role on the database(s) you want to ingest, or the readAnyDatabase role on the admin database.

        • Assign the clusterMonitor role on the admin database.

7. Click Add User.

---

Allowlist Hevo IP Addresses for your Region

You must add Hevo’s IP address for your region to the database IP allowlist, enabling Hevo to connect to your MongoDB database. To do this:

1. Log in to the MongoDB Atlas console.

2. In the left navigation pane, under Security, click Database & Network Access.

   

3. In the left navigation pane, under NETWORK ACCESS, click IP Access List.

   

4. On the IP Access List page, click + ADD IP ADDRESS.

   

5. In the Add IP Access List Entry pop-up window, enter the Hevo IP address you want to allowlist in the Access List Entry field. Repeat this step to allowlist multiple Hevo IP addresses.

   

6. Click Confirm.

---

Retrieve the Cluster Hostname

Perform the following steps to retrieve your cluster hostname:

1. Log in to the MongoDB Atlas console.

2. At the top of the page, from the PROJECT drop-down, select the project for which you want to replicate the data.

   

3. On the Overview page, Clusters section, click Connect.

   

4. In the Connect to <Cluster Name> pop-up window, under Access your data through tools, click Compass.

   

5. In the Connecting with MongoDB Compass section, do the following:

   1. Click I have MongoDB Compass Installed.

      Note: Select this option even if you do not have MongoDB Compass. You do not need MongoDB Compass to configure MongoDB Atlas as a Source in Hevo.

      

   2. Select the version of the MongoDB Compass application. If you do not have Compass installed, select the latest version.

      

6. Copy the connection string that appears in the code block. The connection string varies as per the Compass version you select.

   

   The connection string contains the database username and password, followed by @, the database host, and optional connection options after /. To get the host, remove everything before and including the @ symbol, and everything from the first / after the host onward.

   For example, if the connection string is mongodb+srv://<db_username>:<db_password>@testcluster.cuu2hb8.mongodb.net/?retryWrites=true&w=majority&appName=TestCluster, use testcluster.cuu2hb8.mongodb.net as the host while configuring your MongoDB Atlas Source in Hevo.

---