# MongoDB ## Prerequisites * [x] **The primary key (`_id`) must be a unique, auto-generated** [**ObjectId**](https://www.mongodb.com/docs/manual/reference/bson-types/#std-label-objectid)**.**\ MongoDB's built-in [ObjectId](https://www.mongodb.com/docs/manual/reference/bson-types/#std-label-objectid) is the only data type we support for MongoDB collections' primary keys. * [x] **MongoDB must be running as part of a** [**Replica Set**](https://www.mongodb.com/docs/manual/replication/) **for Stacksync to detect changes from MongoDB** * If you use the **Atlas Database**, no further action is needed. * If you **self-host**, or use a **different managed service**, make sure the MongoDB is configured as a *replica set* by running `rs.status()` in a MongoDB shell. This is required [*even if you only have a single node*](https://www.mongodb.com/community/forums/t/using-change-streams-in-a-standalone-database/127281/2). \ \ 1\. To set up a single-node replica set, run:\ `mongod --port 27017 --dbpath /path/to/data --replSet rs0 --auth --keyFile /path/to/keyfile`\ This assumes you've already set up a key file, otherwise do:\ `echo "" > /path/to/keyfile`\ 2\. Connect to the instance:\ `mongosh "mongodb://localhost:27017"` (don't forget to add username and password)\ 3\. Once inside the instance, you have to go through replica set configuration at least once. A simple example could be:\ `rs.initiate({ _id: "rs0", members: [{ _id: 0, host: "localhost:27017" }] })`.\ \ Check out [the official documentation](https://www.mongodb.com/docs/manual/tutorial/deploy-replica-set/#std-label-server-replica-set-deploy) for more information. {% hint style="success" %} The [oplog](https://www.mongodb.com/docs/manual/core/replica-set-oplog/) and [change streams](https://www.mongodb.com/docs/manual/changeStreams/) are built-in tools managed by MongoDB and leveraged by Stacksync to track changes to your data in real time. Enabling replication is required to make them available. {% endhint %} * [x] **Allow Stacksync IPs**\ Stacksync services must be able to access your MongoDB instance(s). To avoid issues, make sure to whitelist [Stacksync's public IPs](/two-way-sync/connectors/setup-options/ip-whitelisting.md). * [x] **A MongoDB user with the required permissions.**\ The provided MongoDB user should be able to **create collections, read and write from them and also access the oplog.**\ In order to sync, track changes and keep data sources updated, these are necessary. Otherwise, data cannot be accessed.\ \ \- For **Atlas Database**, follow [the official documentation](https://www.mongodb.com/docs/atlas/security-add-mongodb-users/#add-database-users).\ \- For all other deployments, you can run: {% hint style="info" %} We strongly suggest using MongoDB's built-in [`read`](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) or [`readWrite`](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) roles. For more information on how to [create](https://www.mongodb.com/docs/manual/reference/command/createUser/#mongodb-dbcommand-dbcmd.createUser) and [grant roles](https://www.mongodb.com/docs/manual/reference/command/grantRolesToUser/) to users, check out [MongoDB's official documentation](https://www.mongodb.com/docs/manual/reference/database-users/). {% endhint %} 
// Grant user roles without overwriting existing ones (specific DBs)
use admin

const user = db.getUser("<user>");  // Change to your username

const updatedRoles = user.roles.concat([
        { role: "read", db: "local" }, // required to read the oplog and therefore read changes from mongodb
        { role: "readWrite", db: "<db1>" }, // when need to read and write to mongodb
        { role: "read", db: "<db2>" }, // when do not need to write to mongodb
        // Add the database(s) you want Stacksync to have access to
      ]);

db.updateUser("<user>", { roles: updatedRoles });
{% hint style="warning" %} Access must be given at the **database level** for changes to be correctly replicated. Individual collection access is not currently supported. {% endhint %} If a collection you see in your database does not appear in Stacksync, or changes are not correctly replicated, one of the previous conditions is not met. Please double-check your setup in that case. If you have any questions, don't hesitate to contact us at . ## Connecting your MongoDB instance To connect your MongoDB database to Stacksync, you'll need the following data: {% hint style="success" %} You can either enter these fields individually or **simply paste your** [**connection string**](#connection-strings) **directly**. We'll take care of the rest. {% endhint %} * **Protocol**: must be `mongodb+srv://` or `mongodb://`. * **Host**: the URI or IP where the server can be found. * **Port** (optional): the default is usually `27017`. * **Authentication method** * **Username**: name used to authenticate with the server. * **Password**: the password used to authenticate with the server. or * **TLS/SSL** (X.509 Certificate): you must upload your public .pem file. In MongoDB Atlas [you can download it when you create the user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users/#add-database-users):
* **Database**: the name of the database where data is present. * Connection options: * [**Replica Set**](https://www.mongodb.com/docs/manual/reference/connection-string-options/#replica-set-option) (optional): allows you to specify the name of the replica set to connect to. * [**Auth Database**](https://www.mongodb.com/docs/manual/reference/connection-string-options/#mongodb-urioption-urioption.authSource) (optional): the database that holds the user's info. The default is `admin` for username & password, and `$external` for TLS. {% hint style="info" %} Other connection options are not currently supported. If you need special assistance, please contact us at . {% endhint %} * **SSH Tunnel**: * **Username**: The user Stacksync can identify as to establish the tunnel. * **Host**: IP of the machine to SSH into. * **Public Key**: Copy into your machine's `~/.ssh/authorized_keys` file. You can use [ssh-copy-id](https://www.ssh.com/academy/ssh/copy-id) or simply SSH into the server and paste it using your preferred text editor. {% hint style="info" %} SSH tunneling is currently only supported for single, self-hosted MongoDB instances via the mongodb:// protocol. For any further questions, please contact us at . {% endhint %}

The connection setup screen for user+password

The connection setup screen for TLS/SSL

### Connection strings MongoDB has 2 formats for their [connection strings](https://www.mongodb.com/docs/manual/reference/connection-string/). Make sure to pick the one that best suits your use case. {% hint style="success" %} If you're not sure which format to use, **we recommend using the (newer) SRV format**. {% endhint %} * **SRV**: `mongodb+srv://[username:password@]host[/[defaultauthdb][?options]]` *(elements in brackets* `[]` *are optional)* * Example: `mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@cluster0.example.mongodb.net/?retryWrites=true&w=majority` * **Standard**: `mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]` *(elements in brackets* `[]` *are optional)* * Example: `mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl` Find more examples [here](https://www.mongodb.com/docs/manual/reference/connection-string-examples/#std-label-connections-connection-examples). ### Getting your connection string To find out your connection string, check out MongoDB's [official guide for MongoDB Atlas](https://www.mongodb.com/docs/guides/atlas/connection-string/), or [their guide for self-hosted clusters](https://www.mongodb.com/resources/products/fundamentals/mongodb-connection-string#connection-strings-for-a-self-hosted-mongodb-cluster). If you have any questions, don't hesitate to contact us at , we're happy to help! --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.stacksync.com/two-way-sync/connectors/mongodb.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.