> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB

> Power internal tools, in-app experiences, and more

## Overview

The MongoDB destination combines the analytical power of your data warehouse with the low-latency performance of a transactional database. It's been battle-tested with syncs up to hundreds of millions of rows.

## Supported syncing

| Sync Type | Description | Supported Sync Modes |
| - | - | - |
| Documents | Sync data to documents in a MongoDB collection | Upsert |

## Connect to MongoDB

> [!NOTE]
>
> Make sure to allowlist Hightouch IP addresses so Hightouch can reach your cluster. Refer to our
> [IP address docs](https://docs.hightouch.com/security/networking#ip-addresses) to find the relevant IP addresses for your Hightouch region. If you are using Atlas, you can add allowlist IP addresses from **Security > Network Access**.

When creating a MongoDB destination, you can either enter the **Host**, **Port**, **Database**, **User**, and **Password**, or you can provide the full URI connection string. For more information, go to the [official connection guide](https://docs.mongodb.com/drivers/node/current/fundamentals/connection/).

### SSH tunneling

Hightouch can connect directly to MongoDB over the public internet or via an SSH tunnel. Since data is encrypted in transit via TLS, a direct connection is suitable for most use cases. You may need to set up a tunnel if your MongoDB instance is on a private network or virtual private cloud (VPC).

Hightouch supports both standard and reverse SSH tunnels. To learn more about SSH tunneling, refer to Hightouch's [tunneling documentation](https://docs.hightouch.com/security/ssh-tunneling.md).

> [!NOTE]
>
> Through an SSH tunnel, Hightouch connects directly to the single MongoDB host
> and port the tunnel points to. It doesn't use seedlist (SRV) records or
> discover other replica set members, and it ignores the **Is the host name a
> seedlist record?** setting. If you use MongoDB Atlas, point the tunnel at a
> specific node's host name, not a `mongodb+srv` host name.

### Retrieve MongoDB credentials

Assign the user whose credentials you use the built-in [`readWriteAnyDatabase`](https://www.mongodb.com/docs/atlas/security-add-mongodb-users/#mongodb-atlasrole-Read-and-write-to-any-database) MongoDB role or create a [custom role](https://www.mongodb.com/docs/atlas/security-add-mongodb-roles/) and assign these actions at minimum:

| Action | Details |
| :- | :- |
| [`insert`](https://www.mongodb.com/docs/manual/reference/privilege-actions/#mongodb-authaction-insert) | Grants permission to perform `insert` and `create` commands |
| [`remove`](https://www.mongodb.com/docs/manual/reference/privilege-actions/#mongodb-authaction-remove) | Grants permission to perform the `delete` command |
| [`update`](https://www.mongodb.com/docs/manual/reference/privilege-actions/#mongodb-authaction-update) | Grants permission to perform the `update` command |
| [`listIndexes`](https://www.mongodb.com/docs/manual/reference/privilege-actions/#mongodb-authaction-listIndexes) | Grants permission to perform the `listIndexes` command |
| [`listCollections`](https://www.mongodb.com/docs/manual/reference/privilege-actions/#mongodb-authaction-listCollections) | Grants permission to perform the `listCollections` command |

![Custom Role actions](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-mongo-custom-role.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=86195a44029b1f2ccfc5280ea3e7213a)

To create a user in MongoDB, use [`db.createUser()`](https://www.mongodb.com/docs/manual/reference/method/db.createUser/).

#### Authenticate with connection parameters

Enter the following required fields into Hightouch:

* **Host**: The hostname or IP address of your MongoDB server. For help finding this, go to the [official connection guide](https://www.mongodb.com/docs/drivers/node/current/fundamentals/connection/connect/#std-label-node-connect-to-mongodb).
* **Port**: The port number of your MongoDB server. The default port number is 27017, but yours may be different. You don't need to specify the port if you are using SRV protocol.
* **Database**: The name of the your MongoDB database.
* **Username**: This can be your personal MongoDB login or a dedicated user for Hightouch.
* **Password**: This is the password for the user specified above. If you're using [Atlas](https://www.mongodb.com/atlas/database), the user password might differ from the one you use to login to your MongoDB Atlas instance.

- **Is the host name a seedlist record?**: To use [SRV](https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-dns-seedlist) protocol (Hightouch defaults to [standard](https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-standard-connection-string-format)), you must toggle this setting. If you are using MongoDB Atlas and the connection string begins with protocol `mongodb+srv`, toggle this setting to connect.

#### Authenticate with connection string

The connection string is available in multiple locations. Follow these instructions for one way to find it.

1. From the [MongoDB UI](https://cloud.mongodb.com/v2/) click the **Connect** button next to the name of your cluster:

   ![Connect button in MongoDB UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-mongo-connect-button.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=7a00c619b7325df9e782f39dbfa06065)

2. From the options displayed, select **Connect your application**:

   ![Connection options in MongoDB UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-mongo-connect-app.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f4eb5f82ab9793b3a38b40a3aa2578e9)

Follow the instructions for changing the password and database name in the string. Copy the string by clicking the copy icon:

![Connection string in the MongoDB UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-mongo-save-connection-string.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d999302b564784f69cf0c965fabd1775)

In Hightouch, in the MongoDB setup configuration, paste your saved connection string into the provided field.

## Sync configuration

### Record matching

Hightouch requires choosing one column to define how to match data in your source to documents in MongoDB. It's usually best to use the [`_id` field](https://www.mongodb.com/docs/manual/core/document/#the-_id-field) in MongoDB. Otherwise, you can also select `_id (Object ID)` if you already have [Object ID](https://www.mongodb.com/docs/manual/reference/bson-types/#objectid) values in your source data.

You can also choose to record match on a custom MongoDB field. To do this, you need to create a [unique index on a single field](https://www.mongodb.com/docs/manual/core/index-unique/#unique-index-on-a-single-field), which is a specific type of [single field index](https://www.mongodb.com/docs/upcoming/core/indexes/index-types/index-single/#single-field-indexes). Before creating this index, make sure that the field doesn't contain duplicate values, as this makes the index build fail with an `Unknown error` message.

> [!NOTE]
>
> If you record match on a custom field, MongoDB automatically generates an Object ID to insert in the `_id` field.

### Field mapping

You can map the columns you want to include when creating new MongoDB documents or updating existing ones by selecting the model column and typing the respective MongoDB field name. Otherwise, you can include every column from your model by checking the **Sync all columns** box.

### Delete behavior

You can choose how to handle documents in MongoDB when the corresponding rows are deleted in your source.

| Behavior | Description |
| - | - |
| **Do nothing** | Keep the document in MongoDB |
| **Clear Fields** | Clear the mapped fields but keep the document |
| **Delete Destination Record** | Delete the MongoDB document completely |

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

### Best practices

Create a user in MongoDB specifically for Hightouch and only allow that user to access the collections you want Hightouch to access. Don't use the 'root' user.

### Compatible versions

The minimum supported MongoDB version is `4.0`. Earlier versions aren't officially supported but may work regardless.

## Common errors

### MongoServerError: bad auth: Authentication failed

This error can occur if the destination wasn't [configured correctly](#authenticate-with-connection-parameters). Make sure to use the correct password for the user specified in the configuration. If the error is still happening, try changing your MongoDB user's password and attempting the setup again.