> For the complete documentation index, see [llms.txt](https://docs.adiom.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adiom.io/reference/connectors/mongodb.md).

# MongoDB

The MongoDB connector is supported both as a source and a destination. It is built into dsync/dsynct and connects directly using a MongoDB connection string.

## Configuration

Provide a standard MongoDB connection string as the source or destination argument:

```
mongodb://username:password@host:port
```

This works with MongoDB Atlas (dedicated and serverless), self-managed installations, AWS DocumentDB, and Azure DocumentDB (Cosmos DB vCore). Note that change stream features may need to be explicitly enabled for MongoDB emulators unless you plan to run Initial Sync only.

## Data Type

The MongoDB connector uses **BSON**.

## ID Format

The ID is a single field called `_id`. By default, MongoDB uses ObjectID values for `_id`, but any BSON type is supported.

With the `--full-document-key` option, the ID contains every field of the change stream `documentKey` (on sharded collections this includes the shard key fields), each named after its field. The option is accepted on both sides: on the destination it makes writes match on all ID parts instead of `_id` alone.

## Emitted Format

This is what the MongoDB source hands to Dsync, and therefore what a [transformation](/enterprise/running-dsynct/data-transformations.md) receives.

**Namespace:** `database.collection`.

**Initial sync:** each document is emitted exactly as stored. No fields are added, removed or converted.

**CDC:** changes are read from MongoDB change streams with full document lookup.

| Source operation | Event type | ID    | Payload                                                             |
| ---------------- | ---------- | ----- | ------------------------------------------------------------------- |
| insert           | `INSERT`   | `_id` | The full document.                                                  |
| update, replace  | `UPDATE`   | `_id` | The full document as it is when the event is processed, not a diff. |
| delete           | `DELETE`   | `_id` | None.                                                               |

### Example

Source document in `shop.orders`:

```json
{"_id": {"$oid": "65a0f0c2e4b0a1b2c3d4e5f6"}, "customer": "Ann", "qty": {"$numberInt": "1"}}
```

| Stage                     | ID                         | Payload                                                     |
| ------------------------- | -------------------------- | ----------------------------------------------------------- |
| Initial sync              | (part of the document)     | `{"_id": {"$oid": "65a0..."}, "customer": "Ann", "qty": 1}` |
| Insert                    | `_id` = ObjectID `65a0...` | `{"_id": {"$oid": "65a0..."}, "customer": "Ann", "qty": 1}` |
| Update (`$set: {qty: 2}`) | `_id` = ObjectID `65a0...` | `{"_id": {"$oid": "65a0..."}, "customer": "Ann", "qty": 2}` |
| Delete                    | `_id` = ObjectID `65a0...` | None                                                        |

### Things to Know

* Updates always carry the whole document, so a transform never sees which fields changed.
* If a document is updated and then deleted before Dsync processes the update, the update event is skipped and only the delete is emitted.
* Collection-level events such as drop and rename are not replicated. They are logged as `Failed to convert change stream event` errors and skipped.
* The connector supports fetching documents by ID, so it works with `testsync`, Verify IDs and the Sync Tester. Fetching uses the first ID part as `_id`, so with `--full-document-key` on a sharded collection it can miss documents.